Class: SwarmSDK::EventsToMessages

Inherits:
Object
  • Object
show all
Defined in:
lib/swarm_sdk/events_to_messages.rb

Overview

Reconstructs RubyLLM::Message objects from SwarmSDK event streams

This class enables conversation replay and analysis from event logs. It uses timestamps to maintain chronological ordering of messages.

Limitations

This reconstructs ONLY conversation messages. It does NOT restore:

  • Context state (warning thresholds, compression, todowrite index)
  • Scratchpad contents
  • Read tracking information
  • Full swarm state

For full state restoration, use StateSnapshot/StateRestorer or SnapshotFromEvents.

Usage

# Collect events during execution
events = []
swarm.execute("Build feature") do |event|
events << event
end

# Reconstruct conversation for an agent
messages = SwarmSDK::EventsToMessages.reconstruct(events, agent: :backend)

# View conversation
messages.each do |msg|
puts "[#{msg.role}] #{msg.content}"
end

Event Requirements

Events must have:

  • :timestamp field (ISO 8601 format) for ordering
  • :agent field to filter by agent
  • :type field to identify event type

Supported event types:

  • user_prompt: Reconstructs user message (prompt in metadata or top-level)
  • agent_step: Reconstructs assistant message with tool calls
  • agent_stop: Reconstructs final assistant message
  • tool_result: Reconstructs tool result message
  • delegation_result: Reconstructs tool result message from delegation

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(events, agent) ⇒ EventsToMessages

Initialize reconstructor

Parameters:

  • Event stream

  • Agent name



68
69
70
71
 
# File 'lib/swarm_sdk/events_to_messages.rb', line 68

def initialize(events, agent)
  @events = events
  @agent = agent.to_sym
end

Class Method Details

.reconstruct(events, agent:) ⇒ Array<RubyLLM::Message>

Reconstruct messages for an agent from event stream

Examples:

messages = EventsToMessages.reconstruct(events, agent: :backend)
messages.each { |msg| puts msg.content }

Parameters:

  • Event stream with timestamps

  • Agent name to reconstruct messages for

Returns:

  • Reconstructed messages in chronological order



59
60
61
 
# File 'lib/swarm_sdk/events_to_messages.rb', line 59

def reconstruct(events, agent:)
  new(events, agent).reconstruct
end

Instance Method Details

#reconstruct ⇒ Array<RubyLLM::Message>

Reconstruct messages from events

Filters events by agent, sorts by timestamp, and converts to RubyLLM::Message objects.

Returns:

  • Reconstructed messages



78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
 
# File 'lib/swarm_sdk/events_to_messages.rb', line 78

def reconstruct
  messages = []

  # Filter events for this agent and sort by timestamp
  agent_events = @events
    .select { |e| normalize_agent(e[:agent]) == @agent }
    .sort_by { |e| parse_timestamp(e[:timestamp]) }

  agent_events.each do |event|
    message = case event[:type]&.to_s
    when "user_prompt"
      reconstruct_user_message(event)
    when "agent_step", "agent_stop"
      reconstruct_assistant_message(event)
    when "tool_result"
      reconstruct_tool_result_message(event)
    when "delegation_result"
      reconstruct_delegation_result_message(event)
    end

    messages << message if message
  end

  messages
end