Skip to main content

​
compactEvents

compactEvents reduces verbose streaming sequences in an event array while preserving semantics. Use it to shrink logs before persistence or to simplify post‑processing of Server‑Sent Events (SSE) streams.

​
API

​
What it does

  • Text messages: Groups TEXT_MESSAGE_START → TEXT_MESSAGE_CONTENT* → TEXT_MESSAGE_END for the same messageId, concatenating all delta chunks into a single TEXT_MESSAGE_CONTENT event.
  • Tool calls: Groups TOOL_CALL_START → TOOL_CALL_ARGS* → TOOL_CALL_END for the same toolCallId, concatenating all delta chunks into a single TOOL_CALL_ARGS event.
  • Interleaved events: Any events that occur between a start/end pair are moved after that sequence so the streaming block remains contiguous.
  • Pass‑through: All other events (state, custom, etc.) are preserved unchanged.

​
Example

Before:
After:
Tool call compaction works analogously for TOOL_CALL_ARGS chunks.

​
When to use

  • Persisting event history (store fewer frames with the same meaning)
  • Preparing snapshots for analytics or export
  • Reducing noise in tests or debugging output

​
Metadata

Collapsing a run of delta events also folds their metadata, key by key with the last write winning, so a compacted stream produces the same metadata as the original. Metadata that arrives after the first delta — from later deltas and from a replayed start alike — rides the collapsed event in arrival order, because compaction emits the start ahead of it. Compaction reorders events so each stream’s events stay together, and that reordering is not semantics-preserving in general. Two parallel tool calls whose ends arrive in the opposite order to their starts end up swapped in the assistant message’s toolCalls array, each still carrying its own metadata. More significantly, an event that interrupts a stream is emitted after it, so a MESSAGES_SNAPSHOT arriving mid-message is replayed after that message’s own events and overwrites what they produced — the appended content as much as the merged metadata. Avoid interleaving snapshots with an open stream if you rely on exact replay equivalence.

​
Notes & limitations

  • This utility focuses on message and tool‑call streams. It does not modify state events (STATE_SNAPSHOT/STATE_DELTA) or generate message snapshots.
  • For background and broader patterns (branching, normalization), see Serialization.