Enterprise agent platform for building, deploying, and operating AI teammates.
"""Unit tests for ``map_trace_events_to_public_steps``.
The function is intentionally pure (no DB / FastAPI / async) so this
suite can drive synthetic events directly. We use a tiny ``_Event``
namedtuple-ish dict to mimic the attributes the ORM row exposes
(``event_type``, ``data``, ``step_id``, ``timestamp``, ``event_id``,
``task_id``). Anywhere the helper falls back to ``isinstance(event,
dict)`` works too -- but the attribute form is closer to production
behavior.
"""
import copy
from datetime import datetime, timedelta, timezone
from types import SimpleNamespace
from typing import Any, Dict, List, Optional
import pytest
from xagent.web.api.v1._step_mapping import (
PublicStepProjector,
map_trace_events_to_public_steps,
)
from xagent.web.services.task_event_display import convert_display_event
def _ev(
event_type: str,
*,
data: Optional[Dict[str, Any]] = None,
step_id: Optional[str] = None,
task_id: Optional[str] = "t1",
event_id: Optional[str] = None,
timestamp: Optional[datetime] = None,
) -> SimpleNamespace:
"""Build a synthetic event row.
Defaults to a deterministic-ish timestamp so test ordering is
stable. ``event_id`` falls back to a synthetic value if not given.
"""
return SimpleNamespace(
event_type=event_type,
data=data or {},
step_id=step_id,
task_id=task_id,
event_id=event_id or f"evt-{event_type}-{step_id or 'na'}",
timestamp=timestamp or datetime(2026, 1, 1, 12, 0, 0, tzinfo=timezone.utc),
)
def _dag_exec_ev(
phase: str,
*,
task_id: Optional[str] = "t1",
timestamp: Optional[datetime] = None,
**extra_data: Any,
) -> SimpleNamespace:
"""Build a synthetic ``dag_execution`` event.
``phase`` is the only field the projector reads out of ``data``;
``extra_data`` lets callers attach the other fields a real
emission carries (``completed_step_count``, ``plan_step_count``,
``steps``, ...) so a test can prove none of them leak into the
public step.
"""
data: Dict[str, Any] = {"phase": phase, **extra_data}
return _ev("dag_execution", task_id=task_id, data=data, timestamp=timestamp)
# ===== happy paths: each public type appears at least once =====
def test_react_action_pair_becomes_thinking_action():
events: List[SimpleNamespace] = [
_ev("react_action_start", step_id="s1"),
_ev(
"react_action_end",
step_id="s1",
timestamp=datetime(2026, 1, 1, 12, 0, 1, tzinfo=timezone.utc),
),
]
steps = map_trace_events_to_public_steps(events)
assert len(steps) == 1
s = steps[0]
assert s["type"] == "thinking"
assert s["data"]["phase"] == "action"
assert s["status"] == "completed"
assert s["completed_at"] > s["started_at"]
def test_dag_step_pair_becomes_thinking_step():
events = [
_ev("dag_step_start", step_id="s2"),
_ev(
"dag_step_end",
step_id="s2",
timestamp=datetime(2026, 1, 1, 12, 0, 1, tzinfo=timezone.utc),
),
]
steps = map_trace_events_to_public_steps(events)
assert len(steps) == 1
assert steps[0]["type"] == "thinking"
assert steps[0]["data"]["phase"] == "step"
def test_dag_step_end_with_failed_status_projects_failed():
events = [
_ev("dag_step_start", step_id="s2"),
_ev(
"dag_step_end",
step_id="s2",
data={"status": "failed", "error": "boom"},
timestamp=datetime(2026, 1, 1, 12, 0, 1, tzinfo=timezone.utc),
),
]
steps = map_trace_events_to_public_steps(events)
assert len(steps) == 1
assert steps[0]["status"] == "failed"
def test_dag_step_end_with_completed_status_projects_completed():
events = [
_ev("dag_step_start", step_id="s2"),
_ev(
"dag_step_end",
step_id="s2",
data={"status": "completed"},
timestamp=datetime(2026, 1, 1, 12, 0, 1, tzinfo=timezone.utc),
),
]
steps = map_trace_events_to_public_steps(events)
assert len(steps) == 1
assert steps[0]["status"] == "completed"
def test_dag_step_end_missing_status_key_defaults_to_completed():
events = [
_ev("dag_step_start", step_id="s2"),
_ev(
"dag_step_end",
step_id="s2",
timestamp=datetime(2026, 1, 1, 12, 0, 1, tzinfo=timezone.utc),
),
]
steps = map_trace_events_to_public_steps(events)
assert len(steps) == 1
assert steps[0]["status"] == "completed"
@pytest.mark.parametrize("raw_status", ["interrupted", "cancelled", None])
def test_dag_step_end_unrecognized_status_falls_back_to_completed(raw_status):
"""Any ``data['status']`` other than the literal ``"failed"`` must
fold to ``"completed"`` -- not pass through verbatim. This pins the
fallback against a refactor that swaps the dedicated helper for a
direct ``_data_get(event, "status", "completed")`` passthrough:
the three existing status tests above (``"failed"``, ``"completed"``,
missing key) all coincide with a passthrough's output and would
stay green even if an unrecognized value like ``"interrupted"``
leaked straight into ``PublicStepStatus``, which does not accept it.
"""
data = {} if raw_status is None else {"status": raw_status}
events = [
_ev("dag_step_start", step_id="s2"),
_ev(
"dag_step_end",
step_id="s2",
data=data,
timestamp=datetime(2026, 1, 1, 12, 0, 1, tzinfo=timezone.utc),
),
]
steps = map_trace_events_to_public_steps(events)
assert len(steps) == 1
assert steps[0]["status"] == "completed"
def test_dag_plan_pair_becomes_thinking_planning():
events = [
_ev("dag_plan_start", task_id="t1"),
_ev(
"dag_plan_end",
task_id="t1",
timestamp=datetime(2026, 1, 1, 12, 0, 2, tzinfo=timezone.utc),
),
]
steps = map_trace_events_to_public_steps(events)
assert len(steps) == 1
assert steps[0]["type"] == "thinking"
assert steps[0]["data"]["phase"] == "planning"
def test_two_dag_plan_pairs_produce_two_separate_steps():
"""Replan in one task: two dag_plan_start/end pairs must produce
two distinct planning steps (regression for the previous
pair-key collision where both used ``plan:{task_id}`` and the
second start silently overwrote the first's pending entry).
"""
events = [
_ev(
"dag_plan_start",
task_id="t1",
timestamp=datetime(2026, 1, 1, 12, 0, 0, tzinfo=timezone.utc),
),
_ev(
"dag_plan_end",
task_id="t1",
timestamp=datetime(2026, 1, 1, 12, 0, 1, tzinfo=timezone.utc),
),
_ev(
"dag_plan_start",
task_id="t1",
timestamp=datetime(2026, 1, 1, 12, 0, 2, tzinfo=timezone.utc),
),
_ev(
"dag_plan_end",
task_id="t1",
timestamp=datetime(2026, 1, 1, 12, 0, 3, tzinfo=timezone.utc),
),
]
steps = map_trace_events_to_public_steps(events)
assert len(steps) == 2
assert all(
s["type"] == "thinking" and s["data"]["phase"] == "planning" for s in steps
)
# IDs must differ so SDK clients can dedupe across re-polls.
assert steps[0]["id"] != steps[1]["id"]
# Sorted by started_at -> first pair before second.
assert steps[0]["started_at"] < steps[1]["started_at"]
def test_tool_execution_pair_becomes_tool_call_with_args_and_result():
events = [
_ev(
"tool_execution_start",
step_id="s3",
data={
"tool_name": "execute_python",
"tool_args": {"code": "print(1)"},
"tool_execution_id": "tx-1",
},
),
_ev(
"tool_execution_end",
step_id="s3",
data={
"tool_name": "execute_python",
"tool_args": {"code": "print(1)"},
"tool_execution_id": "tx-1",
"result": {"output": "1\n"},
"success": True,
},
timestamp=datetime(2026, 1, 1, 12, 0, 3, tzinfo=timezone.utc),
),
]
steps = map_trace_events_to_public_steps(events)
assert len(steps) == 1
s = steps[0]
assert s["type"] == "tool_call"
assert s["status"] == "completed"
assert s["data"]["name"] == "execute_python"
assert s["data"]["args"] == {"code": "print(1)"}
assert s["data"]["result"] == {"output": "1\n"}
assert "error" not in s["data"]
# Contract: tool_call uses ``result``, not ``output``. Only
# agent_delegation steps rename it to ``output``.
assert "output" not in s["data"]
def test_tool_execution_agent_id_tool_becomes_agent_delegation():
"""A canonical ``agent_<id>`` tool routes to agent_delegation."""
events = [
_ev(
"tool_execution_start",
step_id="s4",
data={
"tool_name": "agent_42",
"tool_args": {"text": "hello"},
"tool_execution_id": "tx-2",
},
),
_ev(
"tool_execution_end",
step_id="s4",
data={
"tool_name": "agent_42",
"tool_args": {"text": "hello"},
"tool_execution_id": "tx-2",
"result": {"translated": "你好"},
"success": True,
},
timestamp=datetime(2026, 1, 1, 12, 0, 4, tzinfo=timezone.utc),
),
]
steps = map_trace_events_to_public_steps(events)
assert len(steps) == 1
s = steps[0]
assert s["type"] == "agent_delegation"
assert s["data"]["sub_agent_name"] == "agent_42"
assert s["data"]["input"] == {"text": "hello"}
# Contract: agent_delegation uses ``output`` on the public surface
# (mirrors ``input`` on the start side). The internal field is
# still ``data['result']`` on the end event, but the mapping
# function renames it to ``output`` for this public type.
# ``result`` must NOT appear on agent_delegation steps.
assert s["data"]["output"] == {"translated": "你好"}
assert "result" not in s["data"]
def test_tool_execution_semantic_workforce_tool_becomes_agent_delegation():
"""Semantic Workforce tool names remain agent delegation steps."""
events = [
_ev(
"tool_execution_start",
step_id="s4",
data={
"tool_name": "worker_preproduction_qa__a18",
"tool_args": {"task": "review"},
"tool_execution_id": "tx-workforce",
},
),
_ev(
"tool_execution_end",
step_id="s4",
data={
"tool_name": "worker_preproduction_qa__a18",
"tool_args": {"task": "review"},
"tool_execution_id": "tx-workforce",
"result": {"status": "approved"},
"success": True,
},
timestamp=datetime(2026, 1, 1, 12, 0, 4, tzinfo=timezone.utc),
),
]
steps = map_trace_events_to_public_steps(events)
assert len(steps) == 1
assert steps[0]["type"] == "agent_delegation"
assert steps[0]["data"]["sub_agent_name"] == ("worker_preproduction_qa__a18")
def test_tool_execution_legacy_call_agent_trace_still_maps_to_delegation():
"""Historical traces with ``call_agent_<name>`` remain readable."""
events = [
_ev(
"tool_execution_start",
step_id="s4",
data={
"tool_name": "call_agent_translator",
"tool_args": {"text": "hello"},
"tool_execution_id": "tx-legacy",
},
),
_ev(
"tool_execution_end",
step_id="s4",
data={
"tool_name": "call_agent_translator",
"tool_args": {"text": "hello"},
"tool_execution_id": "tx-legacy",
"result": {"translated": "你好"},
"success": True,
},
timestamp=datetime(2026, 1, 1, 12, 0, 4, tzinfo=timezone.utc),
),
]
steps = map_trace_events_to_public_steps(events)
assert len(steps) == 1
assert steps[0]["type"] == "agent_delegation"
assert steps[0]["data"]["sub_agent_name"] == "translator"
def test_tool_execution_failure_marks_failed_with_error():
events = [
_ev(
"tool_execution_start",
step_id="s5",
data={
"tool_name": "broken_tool",
"tool_args": {},
"tool_execution_id": "tx-3",
},
),
_ev(
"tool_execution_end",
step_id="s5",
data={
"tool_name": "broken_tool",
"tool_args": {},
"tool_execution_id": "tx-3",
"success": False,
"error": "exploded",
},
timestamp=datetime(2026, 1, 1, 12, 0, 5, tzinfo=timezone.utc),
),
]
steps = map_trace_events_to_public_steps(events)
assert len(steps) == 1
assert steps[0]["type"] == "tool_call"
assert steps[0]["status"] == "failed"
assert steps[0]["data"]["error"] == "exploded"
assert "result" not in steps[0]["data"]
def test_tool_execution_failed_event_marks_step_failed():
"""Regression for v2 runtime which emits a dedicated
``tool_execution_failed`` event (TraceCategory.TOOL + ERROR action)
instead of ``tool_execution_end`` with ``success=False``.
Without explicit handling, the pending start was never finalized
and ``GET /steps`` would report the step as still ``running``
forever after a tool failure.
"""
events = [
_ev(
"tool_execution_start",
step_id="s_fail",
data={
"tool_name": "execute_python",
"tool_params": {"code": "1 / 0"},
"tool_call_id": "call-fail",
},
),
_ev(
"tool_execution_failed",
step_id="s_fail",
data={
"tool_name": "execute_python",
"tool_call_id": "call-fail",
"error": "division by zero",
},
timestamp=datetime(2026, 1, 1, 12, 0, 5, tzinfo=timezone.utc),
),
]
steps = map_trace_events_to_public_steps(events)
assert len(steps) == 1
s = steps[0]
assert s["type"] == "tool_call"
assert s["status"] == "failed"
assert s["data"]["error"] == "division by zero"
assert s["completed_at"] > s["started_at"]
def test_v2_tool_params_alias_reads_args():
"""v2 runtime writes ``tool_params`` where v1 writes ``tool_args``.
Mapper should fall back to ``tool_params`` so the public step's
``data.args`` field is populated regardless of which runtime ran.
"""
events = [
_ev(
"tool_execution_start",
step_id="s_v2",
data={
"tool_name": "web_search",
"tool_params": {"query": "xagent"},
"tool_call_id": "call-v2",
},
),
_ev(
"tool_execution_end",
step_id="s_v2",
data={
"tool_name": "web_search",
"tool_call_id": "call-v2",
"result": "search results",
"success": True,
},
timestamp=datetime(2026, 1, 1, 12, 0, 1, tzinfo=timezone.utc),
),
]
steps = map_trace_events_to_public_steps(events)
assert len(steps) == 1
s = steps[0]
assert s["status"] == "completed"
assert s["data"]["name"] == "web_search"
assert s["data"]["args"] == {"query": "xagent"}
assert s["data"]["result"] == "search results"
def test_v2_tool_start_preserves_assistant_content():
events = [
_ev(
"tool_execution_start",
step_id="s_note",
data={
"tool_name": "web_search",
"tool_params": {"query": "ai news"},
"tool_call_id": "call-note",
"assistant_content": "I need current search results first.",
},
),
]
steps = map_trace_events_to_public_steps(events)
assert len(steps) == 1
assert steps[0]["type"] == "tool_call"
assert steps[0]["status"] == "running"
assert steps[0]["data"]["assistant_content"] == (
"I need current search results first."
)
def test_v2_tool_call_id_does_not_collide_within_same_step():
"""Two v2 tool calls under the same ``step_id`` must each get their
own pending entry — pair key has to be the per-invocation
``tool_call_id``, not the shared ``step_id``.
Without this, the second start overwrites the first pending and
the public timeline either loses the first call or pairs an end
event with the wrong pending entry.
"""
events = [
_ev(
"tool_execution_start",
step_id="shared_step",
event_id="evt-1",
data={
"tool_name": "tool_a",
"tool_params": {"q": "a"},
"tool_call_id": "call-a",
},
),
_ev(
"tool_execution_start",
step_id="shared_step",
event_id="evt-2",
data={
"tool_name": "tool_b",
"tool_params": {"q": "b"},
"tool_call_id": "call-b",
},
timestamp=datetime(2026, 1, 1, 12, 0, 1, tzinfo=timezone.utc),
),
_ev(
"tool_execution_end",
step_id="shared_step",
event_id="evt-3",
data={
"tool_name": "tool_a",
"tool_call_id": "call-a",
"result": "result_a",
"success": True,
},
timestamp=datetime(2026, 1, 1, 12, 0, 2, tzinfo=timezone.utc),
),
_ev(
"tool_execution_end",
step_id="shared_step",
event_id="evt-4",
data={
"tool_name": "tool_b",
"tool_call_id": "call-b",
"result": "result_b",
"success": True,
},
timestamp=datetime(2026, 1, 1, 12, 0, 3, tzinfo=timezone.utc),
),
]
steps = map_trace_events_to_public_steps(events)
assert len(steps) == 2, (
f"expected 2 distinct tool_call steps, got {len(steps)}; the second "
f"start likely overwrote the first pending entry"
)
by_name = {s["data"]["name"]: s for s in steps}
assert "tool_a" in by_name and "tool_b" in by_name
assert by_name["tool_a"]["data"]["args"] == {"q": "a"}
assert by_name["tool_a"]["data"]["result"] == "result_a"
assert by_name["tool_b"]["data"]["args"] == {"q": "b"}
assert by_name["tool_b"]["data"]["result"] == "result_b"
def test_user_and_ai_messages_emit_two_message_steps_in_order():
events = [
_ev(
"user_message",
data={"message": "hello"},
timestamp=datetime(2026, 1, 1, 12, 0, 0, tzinfo=timezone.utc),
),
_ev(
"ai_message",
data={"content": "hi back"},
timestamp=datetime(2026, 1, 1, 12, 0, 1, tzinfo=timezone.utc),
),
]
steps = map_trace_events_to_public_steps(events)
assert [s["type"] for s in steps] == ["message", "message"]
assert steps[0]["data"] == {"role": "user", "content": "hello"}
assert steps[1]["data"] == {"role": "assistant", "content": "hi back"}
# Messages have started_at == completed_at and status='completed'
assert steps[0]["started_at"] == steps[0]["completed_at"]
assert steps[0]["status"] == "completed"
def test_agent_message_without_question_channel_is_not_projected():
"""An ordinary outbound notice is progress, not an assistant turn."""
steps = map_trace_events_to_public_steps(
[
_ev(
"agent_message",
data={
"message": "still working",
"message_type": "info",
"expect_response": False,
},
)
]
)
assert steps == []
def test_question_agent_message_is_projected_as_assistant_message():
steps = map_trace_events_to_public_steps(
[
_ev(
"agent_message",
data={
"message": "Which city?",
"message_type": "question",
"expect_response": True,
},
)
]
)
assert steps == [
{
"id": steps[0]["id"],
"type": "message",
"status": "completed",
"started_at": steps[0]["started_at"],
"completed_at": steps[0]["completed_at"],
"data": {"role": "assistant", "content": "Which city?"},
}
]
def _v2_assistant_message_fact(*, sequence: int = 1) -> SimpleNamespace:
return SimpleNamespace(
kind="assistant_message",
payload_version=1,
payload={
"data": {
"content": "the final answer",
"message_type": "assistant_response",
},
"protocol_event_id": "assistant-fact",
},
event_id="assistant-fact",
task_id=1,
turn_id="turn-1",
occurred_at=datetime(2026, 1, 1, 12, 0, 0, tzinfo=timezone.utc),
sequence=sequence,
run_id="run-1",
)
def test_v2_assistant_message_conversion_does_not_duplicate_steps_or_sse():
"""``convert_display_event`` turns a v2 ``assistant_message`` into an
``agent_message`` with ``expect_response=False`` and its real
``message_type``. The same final answer also arrives as an
``ai_message`` trace; projecting both would double it in ``/steps`` and
in the SSE sink. Both drivers must fold to one assistant step.
"""
converted = convert_display_event(_v2_assistant_message_fact(), replay=True)
assert converted is not None
assert converted["event_type"] == "agent_message"
assert converted["data"]["expect_response"] is False
ai_message = _ev(
"ai_message",
data={"content": "the final answer"},
event_id="ai-answer",
)
steps = map_trace_events_to_public_steps([converted, ai_message])
assert [s["data"]["content"] for s in steps if s["type"] == "message"] == [
"the final answer"
]
sse = PublicStepProjector(retain_finished=False)
sse_steps = []
for event in (converted, ai_message):
sse_steps.extend(sse.feed(event))
assert [s["data"]["content"] for s in sse_steps if s["type"] == "message"] == [
"the final answer"
]
def _v2_agent_message_fact(
*, message_type: str | None, expect_response: bool
) -> SimpleNamespace:
data: dict[str, Any] = {
"message": "Shall I continue?",
"visible": True,
"expect_response": expect_response,
"metadata": {},
}
if message_type is not None:
data["message_type"] = message_type
return SimpleNamespace(
kind="agent_message",
payload_version=1,
payload={"data": data, "protocol_event_id": "agent-message-fact"},
event_id="agent-message-fact",
task_id=1,
turn_id="turn-1",
occurred_at=datetime(2026, 1, 1, 12, 0, 0, tzinfo=timezone.utc),
sequence=1,
run_id="run-1",
scope_id="root",
)
@pytest.mark.parametrize("message_type", ["question", "confirmation", "info", None])
def test_v2_replayed_waiting_message_still_projects_as_a_question_step(message_type):
"""Replay forces ``expect_response`` False to avoid re-arming the client,
but a ``send_message(expect_response=True)`` of any type is still the
question the task is waiting on, so ``/steps`` must show it."""
converted = convert_display_event(
_v2_agent_message_fact(message_type=message_type, expect_response=True),
replay=True,
)
assert converted is not None
assert converted["data"]["expect_response"] is False
steps = map_trace_events_to_public_steps([converted])
assert [s["data"] for s in steps if s["type"] == "message"] == [
{"role": "assistant", "content": "Shall I continue?"}
]
@pytest.mark.parametrize("message_type", ["info", "confirmation"])
def test_v2_replayed_notice_without_a_wait_is_not_projected(message_type):
converted = convert_display_event(
_v2_agent_message_fact(message_type=message_type, expect_response=False),
replay=True,
)
assert converted is not None
assert "awaiting_response" not in converted["data"]
assert map_trace_events_to_public_steps([converted]) == []
# ===== filtering: non-exposed event types are dropped =====
def test_unexposed_event_types_are_dropped():
"""LLM, memory, dag_execute, react_task, etc. don't surface on the SDK."""
events = [
_ev("llm_call_start", step_id="s1"),
_ev("llm_call_end", step_id="s1"),
_ev("dag_execute_start"),
_ev("dag_execute_end"),
_ev("react_task_start"),
_ev("react_task_end"),
_ev("react_step_start", step_id="s1"),
_ev("react_step_end", step_id="s1"),
_ev("visualization_update"),
_ev("task_completion"),
_ev("trace_error"),
]
steps = map_trace_events_to_public_steps(events)
assert steps == []
# ===== partial pairs =====
def test_start_without_end_is_running():
"""SDK polled mid-step: start seen, no end yet -> status='running'."""
events = [_ev("react_action_start", step_id="s1")]
steps = map_trace_events_to_public_steps(events)
assert len(steps) == 1
assert steps[0]["type"] == "thinking"
assert steps[0]["status"] == "running"
assert steps[0]["completed_at"] is None
def test_orphan_end_is_dropped():
"""End event with no matching start -> nothing emitted (malformed data)."""
events = [_ev("react_action_end", step_id="s1")]
steps = map_trace_events_to_public_steps(events)
assert steps == []
# ===== ordering / multiple steps =====
def test_steps_are_sorted_by_started_at():
"""Out-of-order writes still produce monotonic output."""
events = [
# action that starts LATER but is logged first in this synthetic
# list (e.g. due to async flush ordering in the runtime)
_ev(
"react_action_start",
step_id="late",
timestamp=datetime(2026, 1, 1, 12, 0, 5, tzinfo=timezone.utc),
),
_ev(
"react_action_end",
step_id="late",
timestamp=datetime(2026, 1, 1, 12, 0, 6, tzinfo=timezone.utc),
),
_ev(
"react_action_start",
step_id="early",
timestamp=datetime(2026, 1, 1, 12, 0, 1, tzinfo=timezone.utc),
),
_ev(
"react_action_end",
step_id="early",
timestamp=datetime(2026, 1, 1, 12, 0, 2, tzinfo=timezone.utc),
),
]
steps = map_trace_events_to_public_steps(events)
assert len(steps) == 2
assert steps[0]["id"].endswith(":early")
assert steps[1]["id"].endswith(":late")
assert steps[0]["started_at"] < steps[1]["started_at"]
def test_pending_runs_appear_after_completed_when_started_later():
"""An in-flight step at the tail still sorts last."""
events = [
_ev(
"react_action_start",
step_id="done",
timestamp=datetime(2026, 1, 1, 12, 0, 0, tzinfo=timezone.utc),
),
_ev(
"react_action_end",
step_id="done",
timestamp=datetime(2026, 1, 1, 12, 0, 1, tzinfo=timezone.utc),
),
_ev(
"react_action_start",
step_id="running",
timestamp=datetime(2026, 1, 1, 12, 0, 2, tzinfo=timezone.utc),
),
]
steps = map_trace_events_to_public_steps(events)
assert [s["status"] for s in steps] == ["completed", "running"]
# ===== empty input =====
def test_empty_event_list_returns_empty_steps():
assert map_trace_events_to_public_steps([]) == []
# ===== skill_select_*: surface as tool_call =====
def test_skill_select_pair_becomes_tool_call():
events = [
_ev(
"skill_select_start",
data={"skill_name": "presentation"},
timestamp=datetime(2026, 1, 1, 12, 0, 0, tzinfo=timezone.utc),
),
_ev(
"skill_select_end",
data={"skill_name": "presentation", "result": "ok"},
timestamp=datetime(2026, 1, 1, 12, 0, 1, tzinfo=timezone.utc),
),
]
steps = map_trace_events_to_public_steps(events)
assert len(steps) == 1
s = steps[0]
assert s["type"] == "tool_call"
assert s["data"]["name"] == "presentation"
assert s["status"] == "completed"
# ===== content-key normalization =====
def test_message_content_falls_back_when_message_key_absent():
"""ai_message uses ``data.content``, user_message uses ``data.message``.
Helper normalizes both into the public ``content`` field.
"""
events = [
_ev("user_message", data={"message": "msg-key"}),
_ev(
"ai_message",
data={"content": "content-key"},
timestamp=datetime(2026, 1, 1, 12, 0, 1, tzinfo=timezone.utc),
),
]
steps = map_trace_events_to_public_steps(events)
assert steps[0]["data"]["content"] == "msg-key"
assert steps[1]["data"]["content"] == "content-key"
# ===== timestamp coercion =====
def test_float_timestamp_is_coerced_to_datetime():
"""If the ORM returns a float (epoch) instead of datetime, handle it."""
base = datetime(2026, 1, 1, 12, 0, 0, tzinfo=timezone.utc).timestamp()
events = [
_ev(
"react_action_start",
step_id="s1",
timestamp=base, # type: ignore[arg-type]
),
_ev(
"react_action_end",
step_id="s1",
timestamp=base + 1, # type: ignore[arg-type]
),
]
steps = map_trace_events_to_public_steps(events)
assert isinstance(steps[0]["started_at"], datetime)
assert isinstance(steps[0]["completed_at"], datetime)
assert steps[0]["completed_at"] - steps[0]["started_at"] == timedelta(seconds=1)
# ===== PublicStepProjector <-> batch driver equivalence pin =====
#
# ``map_trace_events_to_public_steps`` is a thin batch driver over
# ``PublicStepProjector`` (from_history + materialized_steps + the
# started_at sort): it holds no folding logic of its own. These cases
# cover every pairing family the module docstring documents
# (thinking/planning incl. replan, tool_call, agent_delegation,
# skill_select, message, orphan start/end, unexposed-type filtering,
# out-of-order timestamps) so the equivalence assertion below pins
# that invariant -- the batch driver can never grow a second copy of
# the folding logic without this test catching the divergence.
_PROJECTOR_EQUIVALENCE_CASES: Dict[str, List[SimpleNamespace]] = {
"react_action_pair": [
_ev("react_action_start", step_id="s1"),
_ev(
"react_action_end",
step_id="s1",
timestamp=datetime(2026, 1, 1, 12, 0, 1, tzinfo=timezone.utc),
),
],
"dag_step_pair": [
_ev("dag_step_start", step_id="s2"),
_ev(
"dag_step_end",
step_id="s2",
timestamp=datetime(2026, 1, 1, 12, 0, 1, tzinfo=timezone.utc),
),
],
"dag_step_failed": [
_ev("dag_step_start", step_id="s2f"),
_ev(
"dag_step_end",
step_id="s2f",
data={"status": "failed", "error": "boom"},
timestamp=datetime(2026, 1, 1, 12, 0, 1, tzinfo=timezone.utc),
),
],
"dag_plan_pair": [
_ev("dag_plan_start", task_id="t1"),
_ev(
"dag_plan_end",
task_id="t1",
timestamp=datetime(2026, 1, 1, 12, 0, 2, tzinfo=timezone.utc),
),
],
"replan_two_plan_pairs": [
_ev(
"dag_plan_start",
task_id="t1",
timestamp=datetime(2026, 1, 1, 12, 0, 0, tzinfo=timezone.utc),
),
_ev(
"dag_plan_end",
task_id="t1",
timestamp=datetime(2026, 1, 1, 12, 0, 1, tzinfo=timezone.utc),
),
_ev(
"dag_plan_start",
task_id="t1",
timestamp=datetime(2026, 1, 1, 12, 0, 2, tzinfo=timezone.utc),
),
_ev(
"dag_plan_end",
task_id="t1",
timestamp=datetime(2026, 1, 1, 12, 0, 3, tzinfo=timezone.utc),
),
],
"dag_plan_orphan_end_no_open_plan": [
_ev("dag_plan_end", task_id="t1"),
],
"tool_call_success": [
_ev(
"tool_execution_start",
step_id="s3",
data={
"tool_name": "execute_python",
"tool_args": {"code": "print(1)"},
"tool_execution_id": "tx-1",
},
),
_ev(
"tool_execution_end",
step_id="s3",
data={
"tool_name": "execute_python",
"tool_args": {"code": "print(1)"},
"tool_execution_id": "tx-1",
"result": {"output": "1\n"},
"success": True,
},
timestamp=datetime(2026, 1, 1, 12, 0, 3, tzinfo=timezone.utc),
),
],
"tool_call_failure": [
_ev(
"tool_execution_start",
step_id="s5",
data={
"tool_name": "broken_tool",
"tool_args": {},
"tool_execution_id": "tx-3",
},
),
_ev(
"tool_execution_end",
step_id="s5",
data={
"tool_name": "broken_tool",
"tool_args": {},
"tool_execution_id": "tx-3",
"success": False,
"error": "exploded",
},
timestamp=datetime(2026, 1, 1, 12, 0, 5, tzinfo=timezone.utc),
),
],
"tool_execution_failed_event": [
_ev(
"tool_execution_start",
step_id="s_fail",
data={
"tool_name": "execute_python",
"tool_params": {"code": "1 / 0"},
"tool_call_id": "call-fail",
},
),
_ev(
"tool_execution_failed",
step_id="s_fail",
data={
"tool_name": "execute_python",
"tool_call_id": "call-fail",
"error": "division by zero",
},
timestamp=datetime(2026, 1, 1, 12, 0, 5, tzinfo=timezone.utc),
),
],
"agent_delegation": [
_ev(
"tool_execution_start",
step_id="s4",
data={
"tool_name": "agent_42",
"tool_args": {"text": "hello"},
"tool_execution_id": "tx-2",
},
),
_ev(
"tool_execution_end",
step_id="s4",
data={
"tool_name": "agent_42",
"tool_args": {"text": "hello"},
"tool_execution_id": "tx-2",
"result": {"translated": "你好"},
"success": True,
},
timestamp=datetime(2026, 1, 1, 12, 0, 4, tzinfo=timezone.utc),
),
],
"two_tool_calls_same_step_id": [
_ev(
"tool_execution_start",
step_id="shared_step",
event_id="evt-1",
data={
"tool_name": "tool_a",
"tool_params": {"q": "a"},
"tool_call_id": "call-a",
},
),
_ev(
"tool_execution_start",
step_id="shared_step",
event_id="evt-2",
data={
"tool_name": "tool_b",
"tool_params": {"q": "b"},
"tool_call_id": "call-b",
},
timestamp=datetime(2026, 1, 1, 12, 0, 1, tzinfo=timezone.utc),
),
_ev(
"tool_execution_end",
step_id="shared_step",
event_id="evt-3",
data={
"tool_name": "tool_a",
"tool_call_id": "call-a",
"result": "result_a",
"success": True,
},
timestamp=datetime(2026, 1, 1, 12, 0, 2, tzinfo=timezone.utc),
),
_ev(
"tool_execution_end",
step_id="shared_step",
event_id="evt-4",
data={
"tool_name": "tool_b",
"tool_call_id": "call-b",
"result": "result_b",
"success": True,
},
timestamp=datetime(2026, 1, 1, 12, 0, 3, tzinfo=timezone.utc),
),
],
"tool_start_key_collision": [
_ev(
"tool_execution_start",
step_id="collide",
data={"tool_name": "tool_x", "tool_args": {"a": 1}},
),
_ev(
"tool_execution_start",
step_id="collide",
data={"tool_name": "tool_y", "tool_args": {"b": 2}},
timestamp=datetime(2026, 1, 1, 12, 0, 1, tzinfo=timezone.utc),
),
_ev(
"tool_execution_end",
step_id="collide",
data={"tool_name": "tool_y", "result": "result_y", "success": True},
timestamp=datetime(2026, 1, 1, 12, 0, 2, tzinfo=timezone.utc),
),
],
"skill_select_pair": [
_ev(
"skill_select_start",
data={"skill_name": "presentation"},
timestamp=datetime(2026, 1, 1, 12, 0, 0, tzinfo=timezone.utc),
),
_ev(
"skill_select_end",
data={"skill_name": "presentation", "result": "ok"},
timestamp=datetime(2026, 1, 1, 12, 0, 1, tzinfo=timezone.utc),
),
],
"user_and_ai_messages": [
_ev(
"user_message",
data={"message": "hello"},
timestamp=datetime(2026, 1, 1, 12, 0, 0, tzinfo=timezone.utc),
),
_ev(
"ai_message",
data={"content": "hi back"},
timestamp=datetime(2026, 1, 1, 12, 0, 1, tzinfo=timezone.utc),
),
],
"start_without_end_is_running": [
_ev("react_action_start", step_id="s1"),
],
"orphan_end_is_dropped": [
_ev("react_action_end", step_id="s1"),
],
"out_of_order_timestamps": [
_ev(
"react_action_start",
step_id="late",
timestamp=datetime(2026, 1, 1, 12, 0, 5, tzinfo=timezone.utc),
),
_ev(
"react_action_end",
step_id="late",
timestamp=datetime(2026, 1, 1, 12, 0, 6, tzinfo=timezone.utc),
),
_ev(
"react_action_start",
step_id="early",
timestamp=datetime(2026, 1, 1, 12, 0, 1, tzinfo=timezone.utc),
),
_ev(
"react_action_end",
step_id="early",
timestamp=datetime(2026, 1, 1, 12, 0, 2, tzinfo=timezone.utc),
),
],
"pending_after_completed": [
_ev(
"react_action_start",
step_id="done",
timestamp=datetime(2026, 1, 1, 12, 0, 0, tzinfo=timezone.utc),
),
_ev(
"react_action_end",
step_id="done",
timestamp=datetime(2026, 1, 1, 12, 0, 1, tzinfo=timezone.utc),
),
_ev(
"react_action_start",
step_id="running",
timestamp=datetime(2026, 1, 1, 12, 0, 2, tzinfo=timezone.utc),
),
],
"dag_execution_planning_pair": [
_dag_exec_ev(
"planning",
task_id="t1",
timestamp=datetime(2026, 1, 1, 12, 0, 0, tzinfo=timezone.utc),
completed_step_count=0,
previous_step_count=0,
),
_dag_exec_ev(
"executing",
task_id="t1",
timestamp=datetime(2026, 1, 1, 12, 0, 1, tzinfo=timezone.utc),
plan_step_count=2,
replan=False,
steps=[{"id": "s1"}, {"id": "s2"}],
),
],
"dag_execution_resume_sequence": [
_dag_exec_ev(
"planning",
task_id="t1",
timestamp=datetime(2026, 1, 1, 12, 0, 0, tzinfo=timezone.utc),
),
_dag_exec_ev(
"planning",
task_id="t1",
timestamp=datetime(2026, 1, 1, 12, 0, 1, tzinfo=timezone.utc),
),
_dag_exec_ev(
"executing",
task_id="t1",
timestamp=datetime(2026, 1, 1, 12, 0, 2, tzinfo=timezone.utc),
),
],
"dag_execution_planning_failure": [
_dag_exec_ev(
"planning",
task_id="t1",
timestamp=datetime(2026, 1, 1, 12, 0, 0, tzinfo=timezone.utc),
),
_ev(
"dag_execute_end",
task_id="t1",
data={"status": "failed"},
timestamp=datetime(2026, 1, 1, 12, 0, 1, tzinfo=timezone.utc),
),
],
"dag_plan_and_dag_execution_coexist": [
_ev(
"dag_plan_start",
task_id="t1",
timestamp=datetime(2026, 1, 1, 12, 0, 0, tzinfo=timezone.utc),
),
_dag_exec_ev(
"planning",
task_id="t1",
timestamp=datetime(2026, 1, 1, 12, 0, 1, tzinfo=timezone.utc),
),
_ev(
"dag_plan_end",
task_id="t1",
timestamp=datetime(2026, 1, 1, 12, 0, 2, tzinfo=timezone.utc),
),
_dag_exec_ev(
"executing",
task_id="t1",
timestamp=datetime(2026, 1, 1, 12, 0, 3, tzinfo=timezone.utc),
),
],
"unexposed_event_types_are_dropped": [
_ev("llm_call_start", step_id="s1"),
_ev("llm_call_end", step_id="s1"),
_ev("dag_execute_start"),
_ev("dag_execute_end"),
_ev("react_task_start"),
_ev("react_task_end"),
_ev("react_step_start", step_id="s1"),
_ev("react_step_end", step_id="s1"),
_ev("visualization_update"),
_ev("task_completion"),
_ev("trace_error"),
],
"dag_execute_end_interrupted_does_not_leak_key_to_next_round": [
_ev(
"dag_execute_start",
task_id="t1",
timestamp=datetime(2026, 1, 1, 12, 0, 0, tzinfo=timezone.utc),
),
_dag_exec_ev(
"planning",
task_id="t1",
timestamp=datetime(2026, 1, 1, 12, 0, 1, tzinfo=timezone.utc),
),
_ev(
"dag_execute_end",
task_id="t1",
data={"status": "interrupted"},
timestamp=datetime(2026, 1, 1, 12, 0, 2, tzinfo=timezone.utc),
),
# Round two's dag_execute_start/planning events are lost --
# only the terminal failure survives. The interrupted round
# one end above must have already cleared the open key, or
# this failure would reach back and close round one's
# stranded planning step instead of being a no-op.
_ev(
"dag_execute_end",
task_id="t1",
data={"status": "failed"},
timestamp=datetime(2026, 1, 1, 12, 0, 3, tzinfo=timezone.utc),
),
],
"empty_event_list": [],
}
@pytest.mark.parametrize(
"events",
_PROJECTOR_EQUIVALENCE_CASES.values(),
ids=list(_PROJECTOR_EQUIVALENCE_CASES.keys()),
)
def test_projector_equivalent_to_batch(events):
"""``PublicStepProjector.from_history(events).materialized_steps()``,
sorted by the same ``started_at`` key the batch driver's trailing
sort applies, must equal ``map_trace_events_to_public_steps``
exactly. This is the byte-for-byte pin that the batch function
stays a pure driver over the projector, never a second copy of
the folding logic.
Literal output shapes per event family are already pinned by the
direct-call tests above, which now exercise the projector itself.
What this test guards instead is that the batch driver never grows
a second, independent folding implementation.
It is also the pin on the retention default: this path goes through
``from_history(events).materialized_steps()`` with no override, so a
projector that stopped retaining finished steps by default would
raise rather than return the task's whole timeline here.
"""
expected = map_trace_events_to_public_steps(events)
projected = PublicStepProjector.from_history(events).materialized_steps()
projected.sort(key=lambda s: s["started_at"])
assert projected == expected
@pytest.mark.parametrize(
"events",
_PROJECTOR_EQUIVALENCE_CASES.values(),
ids=list(_PROJECTOR_EQUIVALENCE_CASES.keys()),
)
def test_projector_incremental_feed_matches_materialized_steps(events):
"""Folding the per-event increments ``feed()`` returns (keyed by
step id, last write wins) must reconstruct exactly the same step
objects ``materialized_steps()`` holds afterwards -- pins that the
incremental ``feed()`` view and the projector's own materialized
state can never drift apart.
"""
projector = PublicStepProjector()
by_id: Dict[str, Dict[str, Any]] = {}
for event in events:
for step in projector.feed(event):
by_id[step["id"]] = step
reconstructed = sorted(by_id.values(), key=lambda s: s["id"])
materialized = sorted(projector.materialized_steps(), key=lambda s: s["id"])
assert reconstructed == materialized
@pytest.mark.parametrize(
"events",
_PROJECTOR_EQUIVALENCE_CASES.values(),
ids=list(_PROJECTOR_EQUIVALENCE_CASES.keys()),
)
def test_projector_without_retention_returns_the_same_steps_and_keeps_none(events):
"""``retain_finished=False`` changes only what the projector keeps
after ``feed()`` returns, never what ``feed()`` itself returns.
Feeds the same event sequence into a retaining and a non-retaining
projector in lockstep, deep-copying each ``feed()`` result
immediately (the same reason ``test_feed_return_value_reflects_step_
state_at_call_time`` does -- a returned dict is mutated in place
when its end event later arrives, and a non-retaining projector
still hands back that same live object, it just doesn't also keep
it in ``_finished``). The two sequences must be equal event-for-
event. Afterwards, the non-retaining projector's ``_finished`` is
``None`` and ``materialized_steps()`` raises rather than returning a
silently partial timeline.
"""
retaining = PublicStepProjector()
non_retaining = PublicStepProjector(retain_finished=False)
retaining_results = []
non_retaining_results = []
for event in events:
retaining_results.append(copy.deepcopy(retaining.feed(event)))
non_retaining_results.append(copy.deepcopy(non_retaining.feed(event)))
assert retaining_results == non_retaining_results
assert non_retaining._finished is None
with pytest.raises(RuntimeError):
non_retaining.materialized_steps()
def test_feed_return_value_reflects_step_state_at_call_time():
"""``feed()``'s return is the same dict object later mutated in place
when the matching end event finalizes the step -- so a caller that
wants to know what a step looked like *at the moment of a given
feed() call* must deep-copy the return value immediately, which is
exactly what this test does. Without the ``copy.deepcopy`` calls
below, ``start_steps[0]`` would silently become the finalized
``completed`` step by the time the last assertion runs, and this
test could only ever observe the terminal state.
"""
projector = PublicStepProjector()
start_steps = copy.deepcopy(
projector.feed(
_ev(
"react_action_start",
step_id="s1",
timestamp=datetime(2026, 1, 1, 12, 0, 0, tzinfo=timezone.utc),
)
)
)
assert len(start_steps) == 1
assert start_steps[0]["status"] == "running"
assert start_steps[0]["completed_at"] is None
end_steps = copy.deepcopy(
projector.feed(
_ev(
"react_action_end",
step_id="s1",
timestamp=datetime(2026, 1, 1, 12, 0, 1, tzinfo=timezone.utc),
)
)
)
assert len(end_steps) == 1
assert end_steps[0]["status"] == "completed"
assert end_steps[0]["completed_at"] is not None
# Proof the deep copy above actually decoupled the snapshot: the
# start-time copy must still read "running" now that the live
# object backing the un-copied return value has been mutated to
# "completed" by the end event.
assert start_steps[0]["status"] == "running"
assert start_steps[0]["completed_at"] is None
# Orphan end (no matching start): dropped silently, nothing to feed back.
assert PublicStepProjector().feed(_ev("react_action_end", step_id="orphan")) == []
# Unexposed event type: not part of the public step contract.
assert PublicStepProjector().feed(_ev("llm_call_start", step_id="s1")) == []
# Empty/falsy event_type: nothing identifiable to fold.
assert PublicStepProjector().feed(_ev("", step_id="s1")) == []
# ===== dag_execution: planning-phase visibility from an existing signal =====
def test_dag_execution_planning_pair_becomes_thinking_planning():
events = [
_dag_exec_ev(
"planning",
task_id="t1",
timestamp=datetime(2026, 1, 1, 12, 0, 0, tzinfo=timezone.utc),
completed_step_count=0,
previous_step_count=0,
),
_dag_exec_ev(
"executing",
task_id="t1",
timestamp=datetime(2026, 1, 1, 12, 0, 1, tzinfo=timezone.utc),
plan_step_count=2,
replan=False,
steps=[{"id": "s1"}, {"id": "s2"}],
),
]
steps = map_trace_events_to_public_steps(events)
assert len(steps) == 1
s = steps[0]
assert s["type"] == "thinking"
assert s["data"]["phase"] == "planning"
assert s["status"] == "completed"
# id shape is pinned separately from the legacy dag_plan_* family
# so the two counters can never collide.
assert s["id"] == "thinking:planning:t1:1"
def test_dag_execution_planning_pair_with_integer_task_id():
events = [
_dag_exec_ev(
"planning",
task_id=42,
timestamp=datetime(2026, 1, 1, 12, 0, 0, tzinfo=timezone.utc),
),
_dag_exec_ev(
"executing",
task_id=42,
timestamp=datetime(2026, 1, 1, 12, 0, 1, tzinfo=timezone.utc),
),
]
steps = map_trace_events_to_public_steps(events)
assert len(steps) == 1
s = steps[0]
# An int task_id must interpolate into the key the same way a str
# one does.
assert s["id"] == "thinking:planning:42:1"
assert s["status"] == "completed"
assert s["completed_at"] == events[1].timestamp
def test_two_dag_execution_planning_entries_produce_two_separate_steps():
"""Each entry into planning -- not just replan -- produces its own
step; a replanning entry reports the same public phase as a first
planning entry.
"""
events = [
_dag_exec_ev(
"planning",
task_id="t1",
timestamp=datetime(2026, 1, 1, 12, 0, 0, tzinfo=timezone.utc),
),
_dag_exec_ev(
"executing",
task_id="t1",
timestamp=datetime(2026, 1, 1, 12, 0, 1, tzinfo=timezone.utc),
),
_dag_exec_ev(
"replanning",
task_id="t1",
timestamp=datetime(2026, 1, 1, 12, 0, 2, tzinfo=timezone.utc),
),
_dag_exec_ev(
"executing",
task_id="t1",
timestamp=datetime(2026, 1, 1, 12, 0, 3, tzinfo=timezone.utc),
),
]
steps = map_trace_events_to_public_steps(events)
assert len(steps) == 2
assert all(s["data"]["phase"] == "planning" for s in steps)
assert all(s["status"] == "completed" for s in steps)
assert steps[0]["id"] == "thinking:planning:t1:1"
assert steps[1]["id"] == "thinking:planning:t1:2"
def test_dag_execution_planning_without_executing_stays_running():
"""No executing row (planning failed or task is still in flight):
the step stays running -- and the output is already non-empty with
the first step reporting phase=planning, i.e. visible without
waiting for the executing row.
"""
events = [_dag_exec_ev("planning", task_id="t1")]
steps = map_trace_events_to_public_steps(events)
assert len(steps) == 1
assert steps[0]["type"] == "thinking"
assert steps[0]["data"]["phase"] == "planning"
assert steps[0]["status"] == "running"
assert steps[0]["completed_at"] is None
def test_dag_execution_planning_failure_does_not_disturb_other_steps():
"""A planning step left running does not block other, unrelated
steps in the same stream from folding normally."""
events = [
_dag_exec_ev(
"planning",
task_id="t1",
timestamp=datetime(2026, 1, 1, 12, 0, 0, tzinfo=timezone.utc),
),
_ev(
"react_action_start",
step_id="s1",
timestamp=datetime(2026, 1, 1, 12, 0, 1, tzinfo=timezone.utc),
),
_ev(
"react_action_end",
step_id="s1",
timestamp=datetime(2026, 1, 1, 12, 0, 2, tzinfo=timezone.utc),
),
]
steps = map_trace_events_to_public_steps(events)
assert len(steps) == 2
planning_step = next(s for s in steps if s["data"]["phase"] == "planning")
action_step = next(s for s in steps if s["data"]["phase"] == "action")
assert planning_step["status"] == "running"
assert action_step["status"] == "completed"
def test_dag_execution_resume_sequence_first_running_second_completed():
"""A resumed-after-interruption sequence (planning, planning,
executing -- no executing between the two plannings) leaves the
first step running and closes only the second."""
events = [
_dag_exec_ev(
"planning",
task_id="t1",
timestamp=datetime(2026, 1, 1, 12, 0, 0, tzinfo=timezone.utc),
),
_dag_exec_ev(
"planning",
task_id="t1",
timestamp=datetime(2026, 1, 1, 12, 0, 1, tzinfo=timezone.utc),
),
_dag_exec_ev(
"executing",
task_id="t1",
timestamp=datetime(2026, 1, 1, 12, 0, 2, tzinfo=timezone.utc),
),
]
steps = map_trace_events_to_public_steps(events)
assert len(steps) == 2
assert steps[0]["status"] == "running"
assert steps[0]["completed_at"] is None
assert steps[1]["status"] == "completed"
assert steps[1]["completed_at"] is not None
assert steps[0]["id"] != steps[1]["id"]
def test_dag_execution_translated_step_data_is_phase_only():
"""The translated step's ``data`` is exactly ``{"phase": ...}`` --
none of the source event's other fields (completed_step_count,
plan_step_count, replan, the full plan step list) leak through,
whether the step is still running or already completed.
"""
running_only = map_trace_events_to_public_steps(
[
_dag_exec_ev(
"planning",
task_id="t1",
completed_step_count=1,
previous_step_count=2,
)
]
)
assert set(running_only[0]["data"].keys()) == {"phase"}
events = [
_dag_exec_ev(
"planning",
task_id="t1",
timestamp=datetime(2026, 1, 1, 12, 0, 0, tzinfo=timezone.utc),
completed_step_count=1,
previous_step_count=2,
),
_dag_exec_ev(
"executing",
task_id="t1",
timestamp=datetime(2026, 1, 1, 12, 0, 1, tzinfo=timezone.utc),
plan_step_count=3,
replan=True,
steps=[{"id": "s1", "task": "do x"}],
),
]
completed = map_trace_events_to_public_steps(events)
assert len(completed) == 1
assert set(completed[0]["data"].keys()) == {"phase"}
assert completed[0]["data"]["phase"] == "planning"
@pytest.mark.parametrize("phase", ["completion_assessment", "some_future_phase"])
def test_dag_execution_other_phases_are_dropped(phase):
"""Phases outside {planning, replanning, executing} are not
translated -- current behavior for dag_execution is preserved."""
events = [_dag_exec_ev(phase, task_id="t1")]
assert map_trace_events_to_public_steps(events) == []
def test_dag_execution_missing_or_malformed_phase_is_dropped():
"""Fail-safe: a missing/non-string ``phase``, or a ``data``
payload that isn't even a dict, falls into the discard branch
instead of raising."""
no_phase = _dag_exec_ev("planning", task_id="t1")
no_phase.data = {}
non_str_phase = _dag_exec_ev("planning", task_id="t1")
non_str_phase.data = {"phase": 123}
none_phase = _dag_exec_ev("planning", task_id="t1")
none_phase.data = {"phase": None}
non_dict_data = _dag_exec_ev("planning", task_id="t1")
non_dict_data.data = None
for event in (no_phase, non_str_phase, none_phase, non_dict_data):
assert PublicStepProjector().feed(event) == []
def test_dag_execution_executing_without_open_planning_is_noop():
"""Orphan executing (no preceding planning start): drops silently,
same policy as an orphan end elsewhere in this module."""
events = [_dag_exec_ev("executing", task_id="t1", plan_step_count=1, steps=[])]
assert map_trace_events_to_public_steps(events) == []
def test_dag_plan_and_dag_execution_coexist_without_id_collision():
"""Legacy dag_plan_* and dag_execution-derived planning steps
interleaved in one stream fold independently: separate counters,
separate open keys, each end pairs with its own family's start,
and the resulting ids never collide.
"""
events = [
_ev(
"dag_plan_start",
task_id="t1",
timestamp=datetime(2026, 1, 1, 12, 0, 0, tzinfo=timezone.utc),
),
_dag_exec_ev(
"planning",
task_id="t1",
timestamp=datetime(2026, 1, 1, 12, 0, 1, tzinfo=timezone.utc),
),
_ev(
"dag_plan_end",
task_id="t1",
timestamp=datetime(2026, 1, 1, 12, 0, 2, tzinfo=timezone.utc),
),
_dag_exec_ev(
"executing",
task_id="t1",
timestamp=datetime(2026, 1, 1, 12, 0, 3, tzinfo=timezone.utc),
),
]
steps = map_trace_events_to_public_steps(events)
assert len(steps) == 2
assert all(
s["type"] == "thinking" and s["data"] == {"phase": "planning"} for s in steps
)
assert all(s["status"] == "completed" for s in steps)
ids = {s["id"] for s in steps}
assert len(ids) == 2
assert ids == {"thinking:plan:t1:1", "thinking:planning:t1:1"}
# ===== dag_execute_end: planning failure closes an open planning step =====
@pytest.mark.parametrize(
"status",
["failed", "interrupted", "waiting_for_user", "completed", "__missing__", None],
)
def test_dag_execute_end_only_failed_closes_open_planning_step(status):
"""Only the literal string "failed" closes the open planning step;
every other observed value -- interrupted, waiting_for_user,
completed, a missing key, or None -- leaves it running. This is
the opposite fallback direction from _terminal_status_from_event,
which this branch does not reuse."""
start = _dag_exec_ev(
"planning",
task_id="t1",
timestamp=datetime(2026, 1, 1, 12, 0, 0, tzinfo=timezone.utc),
)
data = {} if status == "__missing__" else {"status": status}
end = _ev(
"dag_execute_end",
task_id="t1",
data=data,
timestamp=datetime(2026, 1, 1, 12, 0, 1, tzinfo=timezone.utc),
)
steps = map_trace_events_to_public_steps([start, end])
assert len(steps) == 1
step = steps[0]
assert step["type"] == "thinking"
assert step["data"] == {"phase": "planning"}
if status == "failed":
assert step["status"] == "failed"
assert step["completed_at"] is not None
else:
assert step["status"] == "running"
assert step["completed_at"] is None
def test_dag_execute_end_failed_data_is_phase_only():
"""Anti-leak gate: dag_execute_end's data['result'] carries the
full DAG pattern output. The closed step's data must be exactly
{"phase": "planning"}, not a superset."""
start = _dag_exec_ev(
"planning",
task_id="t1",
timestamp=datetime(2026, 1, 1, 12, 0, 0, tzinfo=timezone.utc),
)
end = _ev(
"dag_execute_end",
task_id="t1",
data={
"status": "failed",
"result": {
"success": False,
"error": "plan validation failed",
"step_results": {"s1": {"output": "secret intermediate output"}},
"output": "should never leak",
},
},
timestamp=datetime(2026, 1, 1, 12, 0, 1, tzinfo=timezone.utc),
)
steps = map_trace_events_to_public_steps([start, end])
assert len(steps) == 1
assert set(steps[0]["data"].keys()) == {"phase"}
def test_dag_execute_end_without_open_planning_is_noop():
"""No open planning step to close -- same orphan-end policy as
elsewhere in this module."""
events = [
_ev(
"dag_execute_end",
task_id="t1",
data={"status": "failed"},
)
]
assert map_trace_events_to_public_steps(events) == []
def test_dag_execute_start_clears_stale_open_planning_key():
"""A fresh dag_execute_start clears any planning key left open by
a prior round that never reached a terminal event, so a failure
in the new round can't reach back and close the old round's
stranded planning step (left as-is, still "running")."""
round_one_start = _dag_exec_ev(
"planning",
task_id="t1",
timestamp=datetime(2026, 1, 1, 12, 0, 0, tzinfo=timezone.utc),
)
dag_execute_start_round_two = _ev(
"dag_execute_start",
task_id="t1",
timestamp=datetime(2026, 1, 1, 12, 0, 1, tzinfo=timezone.utc),
)
round_two_failure = _ev(
"dag_execute_end",
task_id="t1",
data={"status": "failed"},
timestamp=datetime(2026, 1, 1, 12, 0, 2, tzinfo=timezone.utc),
)
steps = map_trace_events_to_public_steps(
[round_one_start, dag_execute_start_round_two, round_two_failure]
)
# Round 1's planning step is still open/running -- the round 2
# failure must not have reached back and closed it.
assert len(steps) == 1
assert steps[0]["status"] == "running"
assert steps[0]["completed_at"] is None
def test_dag_execute_start_planning_end_failed_closes_within_round():
"""Pin the in-round production order: start -> planning ->
end(failed) closes the planning step opened by that same round.
Guards the failed-closes path; complements the non-failed
key-clearing coverage in the surrounding tests.
"""
start = _ev(
"dag_execute_start",
task_id="t1",
timestamp=datetime(2026, 1, 1, 12, 0, 0, tzinfo=timezone.utc),
)
planning = _dag_exec_ev(
"planning",
task_id="t1",
timestamp=datetime(2026, 1, 1, 12, 0, 1, tzinfo=timezone.utc),
)
end = _ev(
"dag_execute_end",
task_id="t1",
data={"status": "failed"},
timestamp=datetime(2026, 1, 1, 12, 0, 2, tzinfo=timezone.utc),
)
steps = map_trace_events_to_public_steps([start, planning, end])
assert len(steps) == 1
assert steps[0]["status"] == "failed"
assert steps[0]["completed_at"] is not None
@pytest.mark.parametrize("round_one_status", ["interrupted", "waiting_for_user"])
def test_dag_execute_end_interrupted_does_not_misattribute_next_rounds_failure(
round_one_status,
):
"""Round one ends non-"failed" (its dag_execute_end status is not
the literal "failed", so its planning step is deliberately left
running), and round two's own dag_execute_start and planning
events are lost -- only round two's terminal dag_execute_end
(failed) survives.
``_open_dag_execution_key`` is scoped to the round that opened it:
any dag_execute_end -- close or not -- clears it, since that
round has now ended one way or another. Without that clearing, a
non-"failed" end would leave the key pointing at round one's
still-pending planning step, and round two's failure would reach
back through it and close round one's step as "failed" --
attributing round two's failure to round one's stranded step.
With the key cleared, round two's failure finds no open key and is
a no-op, leaving round one's step running as designed. Parametrized
over the status, since the key clearing is unconditional on status
-- a status-scoped clear (e.g. "interrupted" only) would have
passed this test just as well.
"""
round_one_start = _ev(
"dag_execute_start",
task_id="t1",
timestamp=datetime(2026, 1, 1, 12, 0, 0, tzinfo=timezone.utc),
)
round_one_planning = _dag_exec_ev(
"planning",
task_id="t1",
timestamp=datetime(2026, 1, 1, 12, 0, 1, tzinfo=timezone.utc),
)
round_one_end = _ev(
"dag_execute_end",
task_id="t1",
data={"status": round_one_status},
timestamp=datetime(2026, 1, 1, 12, 0, 2, tzinfo=timezone.utc),
)
# Round two's start and planning events are lost -- only its
# terminal failure arrives.
round_two_end = _ev(
"dag_execute_end",
task_id="t1",
data={"status": "failed"},
timestamp=datetime(2026, 1, 1, 12, 0, 3, tzinfo=timezone.utc),
)
steps = map_trace_events_to_public_steps(
[round_one_start, round_one_planning, round_one_end, round_two_end]
)
assert len(steps) == 1
assert steps[0]["status"] == "running"
assert steps[0]["completed_at"] is None
def test_two_full_rounds_interrupted_then_failed_close_independently():
"""Two complete rounds -- neither drops any event -- each close on
their own terms: round one (interrupted) stays running, round two
(failed) closes as failed. Guards the case where both rounds emit
their full start/planning/end triple, which the key clearing must
leave untouched.
"""
round_one_start = _ev(
"dag_execute_start",
task_id="t1",
timestamp=datetime(2026, 1, 1, 12, 0, 0, tzinfo=timezone.utc),
)
round_one_planning = _dag_exec_ev(
"planning",
task_id="t1",
timestamp=datetime(2026, 1, 1, 12, 0, 1, tzinfo=timezone.utc),
)
round_one_end = _ev(
"dag_execute_end",
task_id="t1",
data={"status": "interrupted"},
timestamp=datetime(2026, 1, 1, 12, 0, 2, tzinfo=timezone.utc),
)
round_two_start = _ev(
"dag_execute_start",
task_id="t1",
timestamp=datetime(2026, 1, 1, 12, 0, 3, tzinfo=timezone.utc),
)
round_two_planning = _dag_exec_ev(
"planning",
task_id="t1",
timestamp=datetime(2026, 1, 1, 12, 0, 4, tzinfo=timezone.utc),
)
round_two_end = _ev(
"dag_execute_end",
task_id="t1",
data={"status": "failed"},
timestamp=datetime(2026, 1, 1, 12, 0, 5, tzinfo=timezone.utc),
)
steps = map_trace_events_to_public_steps(
[
round_one_start,
round_one_planning,
round_one_end,
round_two_start,
round_two_planning,
round_two_end,
]
)
assert len(steps) == 2
round_one_step = next(s for s in steps if s["id"] == "thinking:planning:t1:1")
round_two_step = next(s for s in steps if s["id"] == "thinking:planning:t1:2")
assert round_one_step["status"] == "running"
assert round_one_step["completed_at"] is None
assert round_two_step["status"] == "failed"
assert round_two_step["completed_at"] is not None
@pytest.mark.parametrize("second_step", ["react_same", "react_other"])
def test_settlement_projects_exact_invocation_when_provider_id_repeats(second_step):
base = datetime(2026, 1, 1, 12, 0, tzinfo=timezone.utc)
events = [
_ev(
"tool_execution_start",
step_id="react_same",
timestamp=base,
data={
"tool_name": "approval_gate",
"tool_call_id": "shared",
"invocation_id": "inv-first",
},
),
_ev(
"tool_execution_end",
step_id="react_same",
timestamp=base + timedelta(seconds=1),
data={
"tool_name": "approval_gate",
"tool_call_id": "shared",
"invocation_id": "inv-first",
"result": {"value": "first"},
"success": True,
},
),
_ev(
"tool_execution_start",
step_id=second_step,
timestamp=base + timedelta(seconds=2),
data={
"tool_name": "approval_gate",
"tool_call_id": "shared",
"invocation_id": "inv-second",
},
),
_ev(
"tool_execution_end",
step_id=second_step,
timestamp=base + timedelta(seconds=3),
data={
"tool_name": "approval_gate",
"tool_call_id": "shared",
"invocation_id": "inv-second",
"result": {"status": "waiting_for_user"},
"success": False,
},
),
_ev(
"tool_execution_start",
step_id=second_step,
timestamp=base + timedelta(seconds=4),
data={
"tool_name": "approval_gate",
"tool_call_id": "shared",
"invocation_id": "inv-second",
"settlement_delivery": True,
"original_started_at": (base + timedelta(seconds=2)).timestamp(),
},
),
_ev(
"tool_execution_end",
step_id=second_step,
timestamp=base + timedelta(seconds=5),
data={
"tool_name": "approval_gate",
"tool_call_id": "shared",
"invocation_id": "inv-second",
"settlement_delivery": True,
"result": {"value": "settled"},
"success": True,
},
),
]
steps = map_trace_events_to_public_steps(events)
assert len(steps) == 2
assert [step["data"].get("result") for step in steps] == [
{"value": "first"},
{"value": "settled"},
]
assert all("error" not in step["data"] for step in steps)
def test_settlement_sse_lane_does_not_hijack_another_inflight_invocation():
base = datetime(2026, 1, 1, 12, 0, tzinfo=timezone.utc)
projector = PublicStepProjector(retain_finished=False)
assert projector.feed(
_ev(
"tool_execution_start",
step_id="react-a",
timestamp=base,
data={
"tool_name": "approval_gate",
"tool_call_id": "shared",
"invocation_id": "inv-live",
},
)
)
assert (
projector.feed(
_ev(
"tool_execution_start",
step_id="react-b",
timestamp=base + timedelta(seconds=10),
data={
"tool_name": "approval_gate",
"tool_call_id": "shared",
"invocation_id": "inv-settled",
"settlement_delivery": True,
"original_started_at": (base - timedelta(seconds=5)).timestamp(),
},
)
)
== []
)
[settled] = projector.feed(
_ev(
"tool_execution_end",
step_id="react-b",
data={
"tool_name": "approval_gate",
"tool_call_id": "shared",
"invocation_id": "inv-settled",
"settlement_delivery": True,
"result": {"value": "settled"},
"success": True,
},
)
)
[live] = projector.feed(
_ev(
"tool_execution_end",
step_id="react-a",
data={
"tool_name": "approval_gate",
"tool_call_id": "shared",
"invocation_id": "inv-live",
"result": {"value": "live"},
"success": True,
},
)
)
assert settled["data"]["result"] == {"value": "settled"}
assert settled["started_at"] == base - timedelta(seconds=5)
assert live["data"]["result"] == {"value": "live"}
@pytest.mark.parametrize(
("first_success", "settlement_success", "expected_key"),
[(False, True, "result"), (True, False, "error")],
)
def test_settlement_replaces_stale_outcome_fields_symmetrically(
first_success, settlement_success, expected_key
):
common = {"tool_name": "approval_gate", "tool_call_id": "call-1"}
original_end = {
**common,
"success": first_success,
"result": {"old": True},
"error": "old failure",
}
settlement_end = {
**common,
"settlement_delivery": True,
"success": settlement_success,
"result": {"new": True},
"error": "new failure",
}
steps = map_trace_events_to_public_steps(
[
_ev("tool_execution_start", step_id="react-a", data=common),
_ev("tool_execution_end", step_id="react-a", data=original_end),
_ev(
"tool_execution_start",
step_id="react-a",
data={**common, "settlement_delivery": True},
),
_ev(
"tool_execution_end" if settlement_success else "tool_execution_failed",
step_id="react-a",
data=settlement_end,
),
]
)
assert len(steps) == 1
assert set(steps[0]["data"]).intersection({"error", "result"}) == {expected_key}