feat(events): add span events and real-time streaming infrastructure

[vilsonrodrigues]

Summary

Add new events.py module with span events and real-time streaming infrastructure.

Changes

• EventType: 15 constants following OpenTelemetry GenAI semantic conventions (gen_ai.agent.start, gen_ai.tool.call, etc.)
• StreamEvent: Frozen dataclass with name, attributes, timestamp_ns, span_name, span_id, trace_id
• add_event(): Dual emission to span.add_event() (persistence) AND streaming queue (real-time)
• Convenience functions: add_tool_call_event(), add_model_response_chunk_event(), etc.
• EventStream: Context manager for astream() consumers

How it works

from msgtrace.sdk import add_event, EventType, EventStream

# Dual emission: OTel span + streaming queue
add_event(EventType.TOOL_CALL, {
    "tool_name": "search",
    "tool_id": "call_123",
})

# Real-time streaming
async with EventStream() as stream:
    task = asyncio.create_task(agent.acall("Hello"))
    async for event in stream:
        print(event.name, event.attributes)
    await task

Benefits

Aspect	Benefit
Single source of truth	Events go to OTel spans (persisted) AND streaming queue
Zero overhead	When not streaming, only span.add_event() is called
Semantic conventions	Uses gen_ai.* namespace (OpenTelemetry standard)
Hierarchy preserved	trace_id/span_id in StreamEvent for correlation

Test plan

• All 103 tests pass (69 existing + 34 new)
• EventType constants
• StreamEvent dataclass (creation, immutability)
• add_event() with/without span, with complex attributes
• All convenience event functions
• EventStream sync/async context
• EventStream captures events, callbacks, ordering
• Integration tests (nested spans, streaming simulation)

🤖 Generated with Claude Code