Class: SwarmSDK::SnapshotFromEvents

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

Overview

Reconstructs a complete StateSnapshot from event logs

This class enables full swarm state reconstruction from event streams, supporting session persistence, time travel debugging, and event sourcing.

Usage

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

# Save events to storage (DB, file, Redis, etc.)
File.write("session.json", JSON.generate(events))

# Later: Reconstruct snapshot from events
events = JSON.parse(File.read("session.json"), symbolize_names: true)
snapshot_data = SwarmSDK::SnapshotFromEvents.reconstruct(events)

# Restore swarm from reconstructed snapshot
swarm = SwarmSDK::Swarm.from_config("swarm.yml")
swarm.restore(snapshot_data)

What Gets Reconstructed

  • Swarm metadata (swarm_id, parent_swarm_id, first_message_sent)
  • Agent conversations (all RubyLLM::Message objects)
  • Agent context state (warnings, compression, todowrite, skills)
  • Delegation instance conversations
  • Scratchpad contents
  • Read tracking with digests
  • Memory read tracking with digests

Requirements

Events must have:

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

See Also:

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(events) ⇒ SnapshotFromEvents

Initialize reconstructor

Parameters:

  • events (Array<Hash>) —

    Event stream



62
63
64
65
 
# File 'lib/swarm_sdk/snapshot_from_events.rb', line 62

def initialize(events)
  # Sort events by timestamp for chronological processing
  @events = events.sort_by { |e| parse_timestamp(e[:timestamp]) }
end

Class Method Details

.reconstruct(events) ⇒ Hash

Reconstruct a complete StateSnapshot from event stream

Examples:

snapshot_data = SnapshotFromEvents.reconstruct(events)
swarm.restore(snapshot_data)

Parameters:

  • events (Array<Hash>) —

    Event stream with timestamps

Returns:

  • (Hash) —

    Complete StateSnapshot hash compatible with StateRestorer



54
55
56
 
# File 'lib/swarm_sdk/snapshot_from_events.rb', line 54

def reconstruct(events)
  new(events).reconstruct
end

Instance Method Details

#reconstruct ⇒ Hash

Reconstruct complete snapshot

Returns:

  • (Hash) —

    StateSnapshot hash



70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
 
# File 'lib/swarm_sdk/snapshot_from_events.rb', line 70

def reconstruct
  {
    version: "2.1.0",
    type: "swarm",
    snapshot_at: @events.last&.fetch(:timestamp, Time.now.utc.iso8601),
    swarm_sdk_version: SwarmSDK::VERSION,
    metadata: reconstruct_swarm_metadata,
    agents: reconstruct_all_agents,
    delegation_instances: reconstruct_all_delegations,
    scratchpad: reconstruct_scratchpad,
    read_tracking: reconstruct_read_tracking,
    memory_read_tracking: reconstruct_memory_read_tracking,
    plugin_states: reconstruct_plugin_states,
  }
end