Module: SwarmSDK::Concerns::Snapshotable

Included in:
Swarm
Defined in:
lib/swarm_sdk/concerns/snapshotable.rb

Overview

Shared snapshot and restore functionality for Swarm and Workflow

Both classes must implement:

  • primary_agents: Returns hash of primary agent instances
  • delegation_instances_hash: Returns hash of delegation instances
  • agent_definitions: Returns hash of agent definitions
  • swarm_id: Returns the swarm/workflow ID
  • parent_swarm_id: Returns the parent ID (or nil)
  • name: Returns the swarm/workflow name

Instance Method Summary collapse

Instance Method Details

#delegation_instances_hash ⇒ Hash<String, Agent::Chat>

Interface method: Get delegation instance hash

Must be implemented by including class.

Returns:

  • (Hash<String, Agent::Chat>) —

    Delegation instances with keys like "delegate@delegator"

Raises:

  • (NotImplementedError) 


62
63
64
 
# File 'lib/swarm_sdk/concerns/snapshotable.rb', line 62

def delegation_instances_hash
  raise NotImplementedError, "#{self.class} must implement #delegation_instances_hash"
end

#primary_agents ⇒ Hash<Symbol, Agent::Chat>

Interface method: Get primary agent instances

Must be implemented by including class.

Returns:

  • (Hash<Symbol, Agent::Chat>) —

    Primary agent instances

Raises:

  • (NotImplementedError) 


53
54
55
 
# File 'lib/swarm_sdk/concerns/snapshotable.rb', line 53

def primary_agents
  raise NotImplementedError, "#{self.class} must implement #primary_agents"
end

#restore(snapshot, preserve_system_prompts: false) ⇒ RestoreResult

Restore conversation state from snapshot

Accepts a Snapshot object, hash, or JSON string. Validates compatibility between snapshot and current configuration, restores agent conversations, context state, scratchpad, and read tracking.

The swarm/workflow must be created with the SAME configuration (agent definitions, tools, prompts) as when the snapshot was created. Only conversation state is restored from the snapshot.

Parameters:

  • snapshot (Snapshot, Hash, String) —

    Snapshot object, hash, or JSON string

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

    Use historical system prompts instead of current config (default: false)

Returns:



44
45
46
 
# File 'lib/swarm_sdk/concerns/snapshotable.rb', line 44

def restore(snapshot, preserve_system_prompts: false)
  StateRestorer.new(self, snapshot, preserve_system_prompts: preserve_system_prompts).restore
end

#snapshot ⇒ Snapshot

Create snapshot of current conversation state

Returns a Snapshot object containing:

  • All agent conversations (@messages arrays)
  • Agent context state (warnings, compression, TodoWrite tracking, skills)
  • Delegation instance conversations
  • Scratchpad contents (volatile shared storage)
  • Read tracking state (which files each agent has read with digests)
  • Memory read tracking state (which memory entries each agent has read with digests)

Returns:

  • (Snapshot) —

    Snapshot object with convenient serialization methods



27
28
29
 
# File 'lib/swarm_sdk/concerns/snapshotable.rb', line 27

def snapshot
  StateSnapshot.new(self).snapshot
end