Class: SwarmSDK::StateRestorer

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

Overview

Restores swarm/workflow conversation state from snapshots

Unified implementation that works for both Swarm and Workflow. Validates compatibility between snapshot and current configuration, restores conversation history, context state, scratchpad contents, and read tracking information.

Handles configuration mismatches gracefully by skipping agents that don't exist in the current swarm/workflow and returning warnings in RestoreResult.

System Prompt Handling

By default, system prompts are taken from the current YAML configuration, not from the snapshot. This makes configuration the source of truth and allows you to update system prompts without creating new sessions.

Set preserve_system_prompts: true to use historical prompts from the snapshot (useful for debugging, auditing, or exact reproducibility).

Examples:

Restore with current system prompts (default)

swarm = SwarmSDK.build { ... }
snapshot_data = JSON.parse(File.read("session.json"), symbolize_names: true)
result = swarm.restore(snapshot_data)
# Uses system prompts from current YAML config

Restore with historical system prompts

result = swarm.restore(snapshot_data, preserve_system_prompts: true)
# Uses system prompts that were active when snapshot was created

Instance Method Summary collapse

Constructor Details

#initialize(orchestration, snapshot, preserve_system_prompts: false) ⇒ StateRestorer

Initialize state restorer

Parameters:

  • orchestration (Swarm, Workflow) —

    Swarm or workflow to restore into

  • snapshot (Snapshot, Hash, String) —

    Snapshot object, hash, or JSON string

  • preserve_system_prompts (Boolean) (defaults to: false) —

    If true, use system prompts from snapshot instead of current config (default: false)



38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
 
# File 'lib/swarm_sdk/state_restorer.rb', line 38

def initialize(orchestration, snapshot, preserve_system_prompts: false)
  @orchestration = orchestration
  @preserve_system_prompts = preserve_system_prompts

  # Handle different input types
  @snapshot_data = case snapshot
  when Snapshot
    snapshot.to_hash
  when String
    JSON.parse(snapshot, symbolize_names: true)
  when Hash
    snapshot
  else
    raise ArgumentError, "snapshot must be a Snapshot object, Hash, or JSON string"
  end

  validate_version!
  validate_type_match!
end

Instance Method Details

#restore ⇒ RestoreResult

Restore state from snapshot

Three-phase process:

  1. Validate compatibility (which agents can be restored)
  2. Restore state (only for matched agents)
  3. Return result with warnings about skipped agents

Returns:

  • (RestoreResult) —

    Result with warnings about partial restores



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

def restore
  # Phase 1: Validate compatibility
  validation = validate_compatibility

  # Phase 2: Restore state (only for matched agents)
  restore_metadata
  restore_agent_conversations(validation.restorable_agents)
  restore_delegation_conversations(validation.restorable_delegations)
  restore_scratchpad
  restore_read_tracking
  restore_plugin_states

  # Phase 3: Return result with warnings
  SwarmSDK::RestoreResult.new(
    warnings: validation.warnings,
    skipped_agents: validation.skipped_agents,
    skipped_delegations: validation.skipped_delegations,
  )
end