swarm_memory 2.1.5 → 2.1.6

data/lib/swarm_sdk/result.rb

@@ -1,123 +0,0 @@
-# frozen_string_literal: true
-
-module SwarmSDK
-  class Result
-    attr_reader :content, :agent, :duration, :logs, :error, :metadata
-
-    def initialize(content: nil, agent:, cost: nil, tokens: nil, duration: 0.0, logs: [], error: nil, metadata: {})
-      @content = content
-      @agent = agent
-      @duration = duration
-      @logs = logs
-      @error = error
-      @metadata = metadata
-      # Legacy parameters kept for backward compatibility but not stored
-      # Use total_cost and tokens methods instead which calculate from logs
-    end
-
-    def success?
-      @error.nil?
-    end
-
-    def failure?
-      !success?
-    end
-
-    # Calculate total cost from logs
-    #
-    # Delegates to total_cost for consistency. This attribute is calculated
-    # dynamically rather than stored.
-    #
-    # @return [Float] Total cost in dollars
-    def cost
-      total_cost
-    end
-
-    # Get token breakdown from logs
-    #
-    # Returns input and output tokens from the last log entry with usage data.
-    # This attribute is calculated dynamically rather than stored.
-    #
-    # @return [Hash] Token breakdown with :input and :output keys, or empty hash if no usage data
-    def tokens
-      last_entry = @logs.reverse.find { |entry| entry.dig(:usage, :cumulative_input_tokens) }
-      return {} unless last_entry
-
-      {
-        input: last_entry.dig(:usage, :cumulative_input_tokens) || 0,
-        output: last_entry.dig(:usage, :cumulative_output_tokens) || 0,
-      }
-    end
-
-    def to_h
-      {
-        content: @content,
-        agent: @agent,
-        cost: cost,
-        tokens: tokens,
-        duration: @duration,
-        success: success?,
-        error: @error&.message,
-        metadata: @metadata,
-      }.compact
-    end
-
-    def to_json(*args)
-      to_h.to_json(*args)
-    end
-
-    # Calculate total cost across all LLM responses
-    #
-    # Cost accumulation works as follows:
-    # - Input cost: The LAST response's input_cost already includes the cost for the
-    #   full conversation history (all previous messages + current context)
-    # - Output cost: Each response generates NEW tokens, so we SUM all output_costs
-    # - Total = Last input_cost + Sum of all output_costs
-    #
-    # IMPORTANT: Do NOT sum total_cost across all entries - that would count
-    # input costs multiple times since each call includes the full history!
-    def total_cost
-      entries_with_usage = @logs.select { |entry| entry.dig(:usage, :total_cost) }
-      return 0.0 if entries_with_usage.empty?
-
-      # Last entry's input cost (includes full conversation history)
-      last_input_cost = entries_with_usage.last.dig(:usage, :input_cost) || 0.0
-
-      # Sum all output costs (each response generates new tokens)
-      total_output_cost = entries_with_usage.sum { |entry| entry.dig(:usage, :output_cost) || 0.0 }
-
-      last_input_cost + total_output_cost
-    end
-
-    # Get total tokens from the last LLM response with cumulative tracking
-    #
-    # Token accumulation works as follows:
-    # - Input tokens: Each API call sends the full conversation history, so the latest
-    #   response's cumulative_input_tokens already represents the full context
-    # - Output tokens: Each response generates new tokens, cumulative_output_tokens sums them
-    # - The cumulative_total_tokens in the last response already does this correctly
-    #
-    # IMPORTANT: Do NOT sum total_tokens across all log entries - that would count
-    # input tokens multiple times since each call includes the full history!
-    def total_tokens
-      last_entry = @logs.reverse.find { |entry| entry.dig(:usage, :cumulative_total_tokens) }
-      last_entry&.dig(:usage, :cumulative_total_tokens) || 0
-    end
-
-    # Get list of all agents involved in execution
-    def agents_involved
-      @logs.map { |entry| entry[:agent] }.compact.uniq.map(&:to_sym)
-    end
-
-    # Count total LLM requests made
-    # Each LLM API call produces either agent_step (tool calls) or agent_stop (final answer)
-    def llm_requests
-      @logs.count { |entry| entry[:type] == "agent_step" || entry[:type] == "agent_stop" }
-    end
-
-    # Count total tool calls made
-    def tool_calls_count
-      @logs.count { |entry| entry[:type] == "tool_call" }
-    end
-  end
-end

data/lib/swarm_sdk/snapshot.rb

@@ -1,156 +0,0 @@
-# frozen_string_literal: true
-
-module SwarmSDK
-  # Snapshot of swarm conversation state
-  #
-  # Encapsulates snapshot data with methods for serialization and deserialization.
-  # Provides a clean API for saving/loading snapshots in various formats.
-  #
-  # @example Create and save snapshot
-  #   snapshot = swarm.snapshot
-  #   snapshot.write_to_file("session.json")
-  #
-  # @example Load and restore snapshot
-  #   snapshot = SwarmSDK::Snapshot.from_file("session.json")
-  #   result = swarm.restore(snapshot)
-  #
-  # @example Convert to/from hash
-  #   hash = snapshot.to_hash
-  #   snapshot = SwarmSDK::Snapshot.from_hash(hash)
-  class Snapshot
-    attr_reader :data
-
-    # Initialize snapshot with data
-    #
-    # @param data [Hash] Snapshot data hash
-    def initialize(data)
-      @data = data
-    end
-
-    # Convert snapshot to hash
-    #
-    # @return [Hash] Snapshot data as hash
-    def to_hash
-      @data
-    end
-
-    # Convert snapshot to JSON string
-    #
-    # @param pretty [Boolean] Whether to pretty-print JSON (default: true)
-    # @return [String] JSON string
-    def to_json(pretty: true)
-      if pretty
-        JSON.pretty_generate(@data)
-      else
-        JSON.generate(@data)
-      end
-    end
-
-    # Write snapshot to file as JSON
-    #
-    # Uses atomic write pattern (write to temp file, then rename) to prevent
-    # corruption if process crashes during write.
-    #
-    # @param path [String] File path to write to
-    # @param pretty [Boolean] Whether to pretty-print JSON (default: true)
-    # @return [void]
-    def write_to_file(path, pretty: true)
-      # Atomic write: write to temp file, then rename
-      # This ensures the snapshot file is never corrupted even if process crashes
-      temp_path = "#{path}.tmp.#{Process.pid}.#{Time.now.to_i}.#{SecureRandom.hex(4)}"
-
-      File.write(temp_path, to_json(pretty: pretty))
-      File.rename(temp_path, path)
-    rescue
-      # Clean up temp file if it exists
-      File.delete(temp_path) if File.exist?(temp_path)
-      raise
-    end
-
-    class << self
-      # Create snapshot from hash
-      #
-      # @param hash [Hash] Snapshot data hash
-      # @return [Snapshot] New snapshot instance
-      def from_hash(hash)
-        new(hash)
-      end
-
-      # Create snapshot from JSON string
-      #
-      # @param json_string [String] JSON string
-      # @return [Snapshot] New snapshot instance
-      def from_json(json_string)
-        hash = JSON.parse(json_string, symbolize_names: true)
-        new(hash)
-      end
-
-      # Create snapshot from JSON file
-      #
-      # @param path [String] File path to read from
-      # @return [Snapshot] New snapshot instance
-      def from_file(path)
-        json_string = File.read(path)
-        from_json(json_string)
-      end
-    end
-
-    # Get snapshot version
-    #
-    # @return [String] Snapshot version
-    def version
-      @data[:version] || @data["version"]
-    end
-
-    # Get snapshot type (swarm or workflow)
-    #
-    # @return [String] Snapshot type
-    def type
-      @data[:type] || @data["type"]
-    end
-
-    # Get timestamp when snapshot was created
-    #
-    # @return [String] ISO8601 timestamp
-    def snapshot_at
-      @data[:snapshot_at] || @data["snapshot_at"]
-    end
-
-    # Get SwarmSDK version that created this snapshot
-    #
-    # @return [String] SwarmSDK version
-    def swarm_sdk_version
-      @data[:swarm_sdk_version] || @data["swarm_sdk_version"]
-    end
-
-    # Get agent names from snapshot
-    #
-    # @return [Array<String>] Agent names
-    def agent_names
-      agents = @data[:agents] || @data["agents"]
-      agents ? agents.keys.map(&:to_s) : []
-    end
-
-    # Get delegation instance names from snapshot
-    #
-    # @return [Array<String>] Delegation instance names
-    def delegation_instance_names
-      delegations = @data[:delegation_instances] || @data["delegation_instances"]
-      delegations ? delegations.keys.map(&:to_s) : []
-    end
-
-    # Check if snapshot is for a swarm (vs workflow)
-    #
-    # @return [Boolean] true if swarm snapshot
-    def swarm?
-      type == "swarm"
-    end
-
-    # Check if snapshot is for a workflow
-    #
-    # @return [Boolean] true if workflow snapshot
-    def workflow?
-      type == "workflow"
-    end
-  end
-end

data/lib/swarm_sdk/snapshot_from_events.rb

@@ -1,397 +0,0 @@
-# frozen_string_literal: true
-
-module SwarmSDK
-  # 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 EventsToMessages for message reconstruction details
-  class SnapshotFromEvents
-    class << self
-      # Reconstruct a complete StateSnapshot from event stream
-      #
-      # @param events [Array<Hash>] Event stream with timestamps
-      # @return [Hash] Complete StateSnapshot hash compatible with StateRestorer
-      #
-      # @example
-      #   snapshot_data = SnapshotFromEvents.reconstruct(events)
-      #   swarm.restore(snapshot_data)
-      def reconstruct(events)
-        new(events).reconstruct
-      end
-    end
-
-    # Initialize reconstructor
-    #
-    # @param events [Array<Hash>] Event stream
-    def initialize(events)
-      # Sort events by timestamp for chronological processing
-      @events = events.sort_by { |e| parse_timestamp(e[:timestamp]) }
-    end
-
-    # Reconstruct complete snapshot
-    #
-    # @return [Hash] StateSnapshot hash
-    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
-
-    private
-
-    # Reconstruct swarm metadata
-    #
-    # @return [Hash] Swarm metadata
-    def reconstruct_swarm_metadata
-      first_event = @events.first || {}
-
-      {
-        id: first_event[:swarm_id],
-        parent_id: first_event[:parent_swarm_id],
-        first_message_sent: !@events.empty?,
-      }
-    end
-
-    # Reconstruct all primary agents
-    #
-    # @return [Hash] { agent_name => { conversation:, context_state:, system_prompt: } }
-    def reconstruct_all_agents
-      # Get unique primary agent names (exclude delegations with @)
-      agent_names = @events
-        .map { |e| e[:agent] }
-        .compact
-        .uniq
-        .reject { |name| name.to_s.include?("@") }
-
-      agent_names.each_with_object({}) do |agent, hash|
-        hash[agent.to_s] = {
-          conversation: reconstruct_conversation(agent),
-          context_state: reconstruct_context_state(agent),
-          system_prompt: reconstruct_system_prompt(agent),
-        }
-      end
-    end
-
-    # Reconstruct all delegation instances
-    #
-    # @return [Hash] { "delegate@delegator" => { conversation:, context_state:, system_prompt: } }
-    def reconstruct_all_delegations
-      # Get unique delegation instance names (contain @)
-      delegation_names = @events
-        .map { |e| e[:agent] }
-        .compact
-        .uniq
-        .select { |name| name.to_s.include?("@") }
-
-      delegation_names.each_with_object({}) do |delegation, hash|
-        hash[delegation.to_s] = {
-          conversation: reconstruct_conversation(delegation),
-          context_state: reconstruct_context_state(delegation),
-          system_prompt: reconstruct_system_prompt(delegation),
-        }
-      end
-    end
-
-    # Reconstruct conversation for an agent
-    #
-    # @param agent [Symbol, String] Agent name
-    # @return [Array<Hash>] Serialized RubyLLM::Message objects
-    def reconstruct_conversation(agent)
-      messages = SwarmSDK::EventsToMessages.reconstruct(@events, agent: agent)
-      messages.map { |msg| serialize_message(msg) }
-    end
-
-    # Serialize a RubyLLM::Message to hash format
-    #
-    # Matches the format used by StateSnapshot.
-    #
-    # @param msg [RubyLLM::Message] Message to serialize
-    # @return [Hash] Serialized message
-    def serialize_message(msg)
-      hash = { role: msg.role, content: msg.content }
-
-      # Serialize tool calls if present
-      # Must manually extract fields - RubyLLM::ToolCall#to_h doesn't reliably serialize id/name
-      # msg.tool_calls is a Hash<String, ToolCall>, so we need .values
-      if msg.tool_calls && !msg.tool_calls.empty?
-        hash[:tool_calls] = msg.tool_calls.values.map do |tc|
-          {
-            id: tc.id,
-            name: tc.name,
-            arguments: tc.arguments,
-          }
-        end
-      end
-
-      # Add optional fields
-      hash[:tool_call_id] = msg.tool_call_id if msg.tool_call_id
-      hash[:input_tokens] = msg.input_tokens if msg.input_tokens
-      hash[:output_tokens] = msg.output_tokens if msg.output_tokens
-      hash[:model_id] = msg.model_id if msg.model_id
-
-      hash
-    end
-
-    # Reconstruct context state for an agent
-    #
-    # @param agent [Symbol, String] Agent name
-    # @return [Hash] Context state
-    def reconstruct_context_state(agent)
-      {
-        warning_thresholds_hit: reconstruct_warning_thresholds(agent),
-        compression_applied: reconstruct_compression_applied(agent),
-        last_todowrite_message_index: reconstruct_todowrite_index(agent),
-        active_skill_path: reconstruct_active_skill_path(agent),
-      }
-    end
-
-    # Reconstruct which warning thresholds were hit
-    #
-    # @param agent [Symbol, String] Agent name
-    # @return [Array<Integer>] Sorted array of thresholds that were hit
-    def reconstruct_warning_thresholds(agent)
-      @events
-        .select { |e| e[:type] == "context_threshold_hit" && normalize_agent(e[:agent]) == normalize_agent(agent) }
-        .map { |e| e[:threshold] }
-        .uniq
-        .sort
-    end
-
-    # Reconstruct compression state
-    #
-    # @param agent [Symbol, String] Agent name
-    # @return [Boolean, nil] true if compression was applied, nil otherwise
-    def reconstruct_compression_applied(agent)
-      compression_event = @events
-        .select { |e| e[:type] == "compression_completed" && normalize_agent(e[:agent]) == normalize_agent(agent) }
-        .last
-
-      # NOTE: StateSnapshot stores nil (not false) when no compression applied
-      compression_event ? true : nil
-    end
-
-    # Reconstruct last TodoWrite message index
-    #
-    # Finds the last TodoWrite tool call and determines which message index it corresponds to.
-    #
-    # @param agent [Symbol, String] Agent name
-    # @return [Integer, nil] Message index or nil if no TodoWrite calls
-    def reconstruct_todowrite_index(agent)
-      # Find last TodoWrite tool call
-      last_todowrite_call = @events
-        .select { |e| e[:type] == "tool_call" && e[:tool] == "TodoWrite" && normalize_agent(e[:agent]) == normalize_agent(agent) }
-        .sort_by { |e| parse_timestamp(e[:timestamp]) }
-        .last
-
-      return unless last_todowrite_call
-
-      # Reconstruct messages to find index
-      messages = SwarmSDK::EventsToMessages.reconstruct(@events, agent: agent)
-
-      # Find the message containing this tool_call_id
-      messages.each_with_index do |msg, idx|
-        if msg.role == :assistant && msg.tool_calls
-          return idx if msg.tool_calls.key?(last_todowrite_call[:tool_call_id])
-        end
-      end
-
-      nil
-    end
-
-    # Reconstruct active skill path
-    #
-    # @param agent [Symbol, String] Agent name
-    # @return [String, nil] Skill path or nil if no skill loaded
-    def reconstruct_active_skill_path(agent)
-      last_load_skill = @events
-        .select { |e| e[:type] == "tool_call" && e[:tool] == "LoadSkill" && normalize_agent(e[:agent]) == normalize_agent(agent) }
-        .sort_by { |e| parse_timestamp(e[:timestamp]) }
-        .last
-
-      return unless last_load_skill
-
-      # Extract skill path from arguments (handle both symbol and string keys)
-      args = last_load_skill[:arguments]
-      args[:file_path] || args["file_path"]
-    end
-
-    # Reconstruct system prompt from the last agent_start event
-    #
-    # Uses the LAST agent_start event for this agent, which represents the most
-    # recent system prompt that was active. This handles cases where the swarm
-    # was restarted with updated configuration.
-    #
-    # @param agent [Symbol, String] Agent name
-    # @return [String, nil] System prompt or nil if no agent_start event found
-    def reconstruct_system_prompt(agent)
-      last_agent_start = @events
-        .select { |e| e[:type] == "agent_start" && normalize_agent(e[:agent]) == normalize_agent(agent) }
-        .sort_by { |e| parse_timestamp(e[:timestamp]) }
-        .last
-
-      return unless last_agent_start
-
-      # Handle both symbol and string keys from JSON
-      last_agent_start[:system_prompt] || last_agent_start["system_prompt"]
-    end
-
-    # Reconstruct scratchpad contents
-    #
-    # Replays all ScratchpadWrite tool calls in chronological order.
-    # Later writes to the same path overwrite earlier ones.
-    #
-    # @return [Hash] { path => { content:, title:, updated_at:, size: } }
-    def reconstruct_scratchpad
-      scratchpad = {}
-
-      @events
-        .select { |e| e[:type] == "tool_call" && e[:tool] == "ScratchpadWrite" }
-        .sort_by { |e| parse_timestamp(e[:timestamp]) }
-        .each do |event|
-          args = event[:arguments]
-
-          # Handle both symbol and string keys
-          path = args[:file_path] || args["file_path"]
-          content = args[:content] || args["content"]
-          title = args[:title] || args["title"]
-
-          next unless path && content
-
-          scratchpad[path] = {
-            content: content,
-            title: title,
-            updated_at: event[:timestamp],
-            size: content.bytesize,
-          }
-        end
-
-      scratchpad
-    end
-
-    # Reconstruct read tracking (file digests)
-    #
-    # Extracts digests from Read tool_result metadata.
-    # Later reads to the same file update the digest.
-    #
-    # @return [Hash] { agent_name => { file_path => digest } }
-    def reconstruct_read_tracking
-      tracking = {}
-
-      @events
-        .select { |e| e[:type] == "tool_result" && e[:tool] == "Read" }
-        .each do |event|
-          agent = event[:agent].to_s # Use string key to match StateSnapshot format
-          digest = event.dig(:metadata, :read_digest)
-          path = event.dig(:metadata, :read_path)
-
-          next unless digest && path
-
-          tracking[agent] ||= {}
-          tracking[agent][path] = digest
-        end
-
-      tracking
-    end
-
-    # Reconstruct memory read tracking (entry digests)
-    #
-    # Extracts digests from MemoryRead tool_result metadata.
-    # Later reads to the same entry update the digest.
-    #
-    # @return [Hash] { agent_name => { entry_path => digest } }
-    def reconstruct_memory_read_tracking
-      tracking = {}
-
-      @events
-        .select { |e| e[:type] == "tool_result" && e[:tool] == "MemoryRead" }
-        .each do |event|
-          agent = event[:agent].to_s # Use string key to match StateSnapshot format
-          digest = event.dig(:metadata, :read_digest)
-          path = event.dig(:metadata, :read_path)
-
-          next unless digest && path
-
-          tracking[agent] ||= {}
-          tracking[agent][path] = digest
-        end
-
-      tracking
-    end
-
-    # Reconstruct plugin states
-    #
-    # Plugin states cannot be fully reconstructed from events alone as they
-    # contain internal plugin data. Returns empty hash for compatibility.
-    #
-    # @return [Hash] Empty plugin states hash
-    def reconstruct_plugin_states
-      {}
-    end
-
-    # Parse timestamp string to Time object
-    #
-    # @param timestamp [String, nil] ISO 8601 timestamp
-    # @return [Time] Parsed time or epoch if nil/invalid
-    def parse_timestamp(timestamp)
-      return Time.at(0) unless timestamp
-
-      Time.parse(timestamp)
-    rescue ArgumentError
-      Time.at(0)
-    end
-
-    # Normalize agent name for comparison
-    #
-    # @param agent [Symbol, String, nil] Agent name
-    # @return [Symbol] Normalized agent name
-    def normalize_agent(agent)
-      agent.to_s.to_sym
-    end
-  end
-end