TraceEvent

Type-safe, sealed hierarchy of trace events emitted during LLM agent execution.

Each subtype carries the data relevant to one observable moment in the agent lifecycle (completion received, tool executed, token usage recorded, etc.). All subtypes are serialisable to JSON via toJson, which produces a flat object containing at minimum "event_type" and "timestamp" fields.

== Error truncation == ErrorOccurred.toJson includes only the first 5 frames of the stack trace to limit payload size.

== Timestamp default == Every event's companion apply defaults timestamp to Instant.now() at construction time. Override explicitly when replaying historical events or writing deterministic tests.

== Growth safety == Each event is a final case class with a private constructor and copy: build one with its companion apply and change a field with its with* setter (an Option field's setter takes the value or an Option), so a field can be added later without breaking binary compatibility.