swarm_sdk 2.7.13 → 3.0.0.alpha1

data/lib/swarm_sdk/agent/chat_helpers/system_reminders.rb

@@ -1,79 +0,0 @@
-# frozen_string_literal: true
-
-module SwarmSDK
-  module Agent
-    module ChatHelpers
-      # System reminder collection and injection
-      #
-      # Extracted from Chat to reduce class size and centralize reminder logic.
-      module SystemReminders
-        # Collect reminders from all plugins
-        #
-        # @param prompt [String] User's message
-        # @param is_first_message [Boolean] True if first message
-        # @return [Array<String>] Array of reminder strings
-        def collect_plugin_reminders(prompt, is_first_message:)
-          return [] unless @agent_name
-
-          PluginRegistry.all.flat_map do |plugin|
-            plugin.on_user_message(
-              agent_name: @agent_name,
-              prompt: prompt,
-              is_first_message: is_first_message,
-            )
-          end.compact
-        end
-
-        # Collect all system reminders for this message
-        #
-        # Returns an array of reminder strings that should be injected as ephemeral content.
-        # These are sent to the LLM but not stored in message history.
-        #
-        # @param prompt [String] User prompt
-        # @param is_first [Boolean] Whether this is the first message
-        # @return [Array<String>] Array of reminder strings
-        def collect_system_reminders(prompt, is_first)
-          reminders = []
-
-          if is_first
-            # Add toolset reminder on first message
-            reminders << build_toolset_reminder
-
-            # Add todo list reminder if agent has TodoWrite tool
-            reminders << SystemReminderInjector::AFTER_FIRST_MESSAGE_REMINDER if has_tool?(:TodoWrite)
-
-            # Collect plugin reminders
-            reminders.concat(collect_plugin_reminders(prompt, is_first_message: true))
-          else
-            # Add periodic TodoWrite reminder if needed
-            if has_tool?(:TodoWrite) && SystemReminderInjector.should_inject_todowrite_reminder?(self, @last_todowrite_message_index)
-              reminders << SystemReminderInjector::TODOWRITE_PERIODIC_REMINDER
-              @last_todowrite_message_index = SystemReminderInjector.find_last_todowrite_index(self)
-            end
-
-            # Collect plugin reminders
-            reminders.concat(collect_plugin_reminders(prompt, is_first_message: false))
-          end
-
-          reminders
-        end
-
-        private
-
-        # Build toolset reminder listing all available tools
-        #
-        # @return [String] System reminder with tool list
-        def build_toolset_reminder
-          tools_list = tool_names
-
-          reminder = "<system-reminder>\n"
-          reminder += "Tools available: #{tools_list.join(", ")}\n\n"
-          reminder += "Only use tools from this list. Do not attempt to use tools that are not listed here.\n"
-          reminder += "</system-reminder>"
-
-          reminder
-        end
-      end
-    end
-  end
-end

data/lib/swarm_sdk/agent/chat_helpers/token_tracking.rb

@@ -1,146 +0,0 @@
-# frozen_string_literal: true
-
-module SwarmSDK
-  module Agent
-    module ChatHelpers
-      # Token usage tracking and context limit management
-      #
-      # Extracted from Chat to reduce class size and centralize token metrics.
-      module TokenTracking
-        # Get context window limit for the current model
-        #
-        # @return [Integer, nil] Maximum context tokens
-        def context_limit
-          return @explicit_context_window if @explicit_context_window
-          return @real_model_info.context_window if @real_model_info&.context_window
-
-          model_context_window
-        rescue StandardError
-          nil
-        end
-
-        # Calculate cumulative input tokens for the conversation
-        #
-        # Gets input_tokens from the most recent assistant message, which represents
-        # the total context size sent to the model (not sum of all messages).
-        #
-        # @return [Integer] Total input tokens used
-        def cumulative_input_tokens
-          find_last_message { |msg| msg.role == :assistant && msg.input_tokens }&.input_tokens || 0
-        end
-
-        # Calculate cumulative output tokens across all assistant messages
-        #
-        # @return [Integer] Total output tokens used
-        def cumulative_output_tokens
-          assistant_messages.sum { |msg| msg.output_tokens || 0 }
-        end
-
-        # Calculate cumulative cached tokens
-        #
-        # @return [Integer] Total cached tokens used
-        def cumulative_cached_tokens
-          assistant_messages.sum { |msg| msg.cached_tokens || 0 }
-        end
-
-        # Calculate cumulative cache creation tokens
-        #
-        # @return [Integer] Total tokens written to cache
-        def cumulative_cache_creation_tokens
-          assistant_messages.sum { |msg| msg.cache_creation_tokens || 0 }
-        end
-
-        # Calculate effective input tokens (excluding cache hits)
-        #
-        # @return [Integer] Actual input tokens charged
-        def effective_input_tokens
-          cumulative_input_tokens - cumulative_cached_tokens
-        end
-
-        # Calculate total tokens used (input + output)
-        #
-        # @return [Integer] Total tokens used
-        def cumulative_total_tokens
-          cumulative_input_tokens + cumulative_output_tokens
-        end
-
-        # Calculate percentage of context window used
-        #
-        # @return [Float] Percentage (0.0 to 100.0)
-        def context_usage_percentage
-          limit = context_limit
-          return 0.0 if limit.nil? || limit.zero?
-
-          (cumulative_total_tokens.to_f / limit * 100).round(2)
-        end
-
-        # Calculate remaining tokens in context window
-        #
-        # @return [Integer, nil] Tokens remaining
-        def tokens_remaining
-          limit = context_limit
-          return if limit.nil?
-
-          limit - cumulative_total_tokens
-        end
-
-        # Calculate cumulative input cost based on tokens and model pricing
-        #
-        # @return [Float] Total input cost in dollars
-        def cumulative_input_cost
-          pricing = model_pricing
-          return 0.0 unless pricing
-
-          input_price = pricing["input_per_million"] || pricing[:input_per_million] || 0.0
-          (cumulative_input_tokens / 1_000_000.0) * input_price
-        end
-
-        # Calculate cumulative output cost based on tokens and model pricing
-        #
-        # @return [Float] Total output cost in dollars
-        def cumulative_output_cost
-          pricing = model_pricing
-          return 0.0 unless pricing
-
-          output_price = pricing["output_per_million"] || pricing[:output_per_million] || 0.0
-          (cumulative_output_tokens / 1_000_000.0) * output_price
-        end
-
-        # Calculate cumulative total cost (input + output)
-        #
-        # @return [Float] Total cost in dollars
-        def cumulative_total_cost
-          cumulative_input_cost + cumulative_output_cost
-        end
-
-        # Compact the conversation history to reduce token usage
-        #
-        # @param options [Hash] Compression options
-        # @return [ContextCompactor::Metrics] Compression statistics
-        def compact_context(**options)
-          compactor = ContextCompactor.new(self, options)
-          compactor.compact
-        end
-
-        private
-
-        # Get pricing info for the current model
-        #
-        # Extracts standard text token pricing from model info.
-        #
-        # @return [Hash, nil] Pricing hash with input_per_million and output_per_million
-        def model_pricing
-          return unless @real_model_info&.pricing
-
-          pricing = @real_model_info.pricing
-          text_pricing = pricing["text_tokens"] || pricing[:text_tokens]
-          return unless text_pricing
-
-          text_pricing["standard"] || text_pricing[:standard]
-        rescue StandardError
-          nil
-        end
-      end
-    end
-  end
-end

data/lib/swarm_sdk/agent/context.rb

@@ -1,115 +0,0 @@
-# frozen_string_literal: true
-
-module SwarmSDK
-  module Agent
-    # AgentContext encapsulates per-agent state and metadata
-    #
-    # Each agent has its own context that tracks:
-    # - Agent identity (name)
-    # - Delegation relationships (which tool calls are delegations)
-    # - Context window warnings (which thresholds have been hit)
-    # - Optional metadata
-    #
-    # This class replaces the per-agent hash maps that were previously
-    # stored in UnifiedLogger.
-    #
-    # @example
-    #   context = Agent::Context.new(
-    #     name: :backend,
-    #     delegation_tools: ["DelegateToDatabase", "DelegateToAuth"],
-    #     metadata: { role: "backend" }
-    #   )
-    #
-    #   # Track a delegation
-    #   context.track_delegation(call_id: "call_123", target: "DelegateToDatabase")
-    #
-    #   # Check if a tool call is a delegation
-    #   context.delegation?(call_id: "call_123") # => true
-    class Context
-      # Thresholds for context limit warnings (in percentage)
-      # 60% triggers automatic compression, 80%/90% are informational warnings
-      CONTEXT_WARNING_THRESHOLDS = [60, 80, 90].freeze
-
-      # NOTE: Compression threshold now accessed via SwarmSDK.config.context_compression_threshold
-
-      attr_reader :name, :delegation_tools, :metadata, :warning_thresholds_hit, :swarm_id, :parent_swarm_id
-
-      # Initialize a new agent context
-      #
-      # @param name [Symbol, String] Agent name
-      # @param swarm_id [String] Swarm ID for event tracking
-      # @param parent_swarm_id [String, nil] Parent swarm ID (nil for root swarms)
-      # @param delegation_tools [Array<String>] Names of tools that are delegations
-      # @param metadata [Hash] Optional metadata about the agent
-      def initialize(name:, swarm_id:, parent_swarm_id: nil, delegation_tools: [], metadata: {})
-        @name = name.to_sym
-        @swarm_id = swarm_id
-        @parent_swarm_id = parent_swarm_id
-        @delegation_tools = Set.new(delegation_tools.map(&:to_s))
-        @metadata = metadata
-        @delegation_call_ids = Set.new
-        @delegation_targets = {}
-        @warning_thresholds_hit = Set.new
-      end
-
-      # Track a delegation tool call
-      #
-      # @param call_id [String] Tool call ID
-      # @param target [String] Target agent/tool name
-      # @return [void]
-      def track_delegation(call_id:, target:)
-        @delegation_call_ids.add(call_id)
-        @delegation_targets[call_id] = target
-      end
-
-      # Check if a tool call is a delegation
-      #
-      # @param call_id [String] Tool call ID
-      # @return [Boolean]
-      def delegation?(call_id:)
-        @delegation_call_ids.include?(call_id)
-      end
-
-      # Get the delegation target for a tool call
-      #
-      # @param call_id [String] Tool call ID
-      # @return [String, nil] Target agent/tool name, or nil if not a delegation
-      def delegation_target(call_id:)
-        @delegation_targets[call_id]
-      end
-
-      # Remove a delegation from tracking (after it completes)
-      #
-      # @param call_id [String] Tool call ID
-      # @return [void]
-      def clear_delegation(call_id:)
-        @delegation_targets.delete(call_id)
-        @delegation_call_ids.delete(call_id)
-      end
-
-      # Check if a tool name is a delegation tool
-      #
-      # @param tool_name [String] Tool name
-      # @return [Boolean]
-      def delegation_tool?(tool_name)
-        @delegation_tools.include?(tool_name.to_s)
-      end
-
-      # Record that a context warning threshold has been hit
-      #
-      # @param threshold [Integer] Threshold percentage (80, 90, etc)
-      # @return [Boolean] true if this is the first time hitting this threshold
-      def hit_warning_threshold?(threshold)
-        !@warning_thresholds_hit.add?(threshold).nil?
-      end
-
-      # Check if a warning threshold has been hit
-      #
-      # @param threshold [Integer] Threshold percentage
-      # @return [Boolean]
-      def warning_threshold_hit?(threshold)
-        @warning_thresholds_hit.include?(threshold)
-      end
-    end
-  end
-end

data/lib/swarm_sdk/agent/context_manager.rb

@@ -1,315 +0,0 @@
-# frozen_string_literal: true
-
-module SwarmSDK
-  module Agent
-    # Manages conversation context and message optimization
-    #
-    # Responsibilities:
-    # - Handle ephemeral messages (sent to LLM but not persisted)
-    # - Extract and strip system reminders
-    # - Prepare messages for LLM API calls
-    # - Future: Context window management, summarization, truncation
-    #
-    # @example
-    #   manager = ContextManager.new
-    #   manager.add_ephemeral_reminder("<system-reminder>Use caution</system-reminder>")
-    #   messages_for_llm = manager.prepare_for_llm(persistent_messages)
-    #   manager.clear_ephemeral  # After LLM call
-    class ContextManager
-      SYSTEM_REMINDER_REGEX = %r{<system-reminder>.*?</system-reminder>}m
-
-      # Expose compression state for snapshot/restore
-      # NOTE: @compression_applied initializes to nil (not false), only set to true when compression runs
-      attr_reader :compression_applied
-      attr_writer :compression_applied
-
-      def initialize
-        # Ephemeral content to append to messages for this turn only
-        # Format: { message_index => [array of reminder strings] }
-        @ephemeral_content = {}
-        # NOTE: @compression_applied is NOT initialized here - starts as nil
-      end
-
-      # Track ephemeral content to append to a specific message
-      #
-      # Reminders will be embedded in the message content when sent to LLM,
-      # but are NOT persisted in the message history.
-      #
-      # @param message_index [Integer] Index of message to append to
-      # @param content [String] Reminder content to append
-      # @return [void]
-      def add_ephemeral_content_for_message(message_index, content)
-        @ephemeral_content[message_index] ||= []
-        @ephemeral_content[message_index] << content
-      end
-
-      # Add ephemeral reminder to the most recent message
-      #
-      # This will append the reminder to the last message in the array when
-      # preparing for LLM, but won't modify the stored message.
-      #
-      # @param content [String] Reminder content
-      # @param messages_array [Array<RubyLLM::Message>] Message array to get index from
-      # @return [void]
-      def add_ephemeral_reminder(content, messages_array:)
-        message_index = messages_array.size - 1
-        return if message_index < 0
-
-        add_ephemeral_content_for_message(message_index, content)
-      end
-
-      # Prepare messages for LLM API call
-      #
-      # Embeds ephemeral content into messages for this turn only.
-      # Does NOT modify the persistent messages array.
-      #
-      # @param persistent_messages [Array<RubyLLM::Message>] Messages from @messages
-      # @return [Array<RubyLLM::Message>] Messages with ephemeral content embedded
-      def prepare_for_llm(persistent_messages)
-        return persistent_messages.dup if @ephemeral_content.empty?
-
-        # Clone messages and embed ephemeral content
-        messages_for_llm = persistent_messages.map.with_index do |msg, index|
-          ephemeral_for_this_msg = @ephemeral_content[index]
-
-          # No ephemeral content for this message - use as-is
-          next msg unless ephemeral_for_this_msg&.any?
-
-          # Embed ephemeral content in this message
-          original_content = msg.content.is_a?(RubyLLM::Content) ? msg.content.text : msg.content.to_s
-          embedded_content = [original_content, *ephemeral_for_this_msg].join("\n\n")
-
-          # Create new message with embedded content
-          if msg.content.is_a?(RubyLLM::Content)
-            RubyLLM::Message.new(
-              role: msg.role,
-              content: RubyLLM::Content.new(embedded_content, msg.content.attachments),
-              tool_call_id: msg.tool_call_id,
-            )
-          else
-            RubyLLM::Message.new(
-              role: msg.role,
-              content: embedded_content,
-              tool_call_id: msg.tool_call_id,
-            )
-          end
-        end
-
-        messages_for_llm
-      end
-
-      # Clear all ephemeral content
-      #
-      # Should be called after LLM response is received.
-      #
-      # @return [void]
-      def clear_ephemeral
-        @ephemeral_content.clear
-      end
-
-      # Check if there is pending ephemeral content
-      #
-      # @return [Boolean] True if ephemeral content exists
-      def has_ephemeral?
-        @ephemeral_content.any?
-      end
-
-      # Get count of messages with ephemeral content
-      #
-      # @return [Integer] Number of messages with ephemeral content attached
-      def ephemeral_count
-        @ephemeral_content.size
-      end
-
-      # Extract all <system-reminder> blocks from content
-      #
-      # @param content [String] Content to extract from
-      # @return [Array<String>] Array of system reminder blocks
-      def extract_system_reminders(content)
-        return [] if content.nil? || content.empty?
-
-        content.scan(SYSTEM_REMINDER_REGEX)
-      end
-
-      # Strip all <system-reminder> blocks from content
-      #
-      # Returns clean content without system reminders.
-      #
-      # @param content [String] Content to strip from
-      # @return [String] Clean content
-      def strip_system_reminders(content)
-        return content if content.nil? || content.empty?
-
-        content.gsub(SYSTEM_REMINDER_REGEX, "").strip
-      end
-
-      # Check if content contains system reminders
-      #
-      # @param content [String] Content to check
-      # @return [Boolean] True if reminders found
-      def has_system_reminders?(content)
-        return false if content.nil? || content.empty?
-
-        SYSTEM_REMINDER_REGEX.match?(content)
-      end
-
-      # ============================================================================
-      # FUTURE: Context Optimization Methods (Hooks for Later Implementation)
-      # ============================================================================
-
-      # Future: Summarize old messages to save context window space
-      #
-      # @param messages [Array<RubyLLM::Message>] Messages to potentially summarize
-      # @param before_index [Integer] Summarize messages before this index
-      # @param strategy [Symbol] Summarization strategy (:llm, :truncate, :remove)
-      # @return [Array<RubyLLM::Message>] Optimized message array
-      def summarize_old_messages(messages, before_index:, strategy: :truncate)
-        # TODO: Implement when needed
-        messages
-      end
-
-      # Future: Truncate messages to fit within context window
-      #
-      # @param messages [Array<RubyLLM::Message>] Messages to fit
-      # @param max_tokens [Integer] Maximum token budget
-      # @param keep_recent [Integer] Number of recent messages to always keep
-      # @return [Array<RubyLLM::Message>] Truncated messages
-      def truncate_to_fit(messages, max_tokens:, keep_recent: 10)
-        # TODO: Implement when needed
-        messages
-      end
-
-      # Compress verbose tool results for older messages
-      #
-      # Uses progressive compression: older messages are compressed more aggressively.
-      # Preserves user/assistant messages at full detail (conversational context).
-      #
-      # @param messages [Array<RubyLLM::Message>] Messages to compress
-      # @param keep_recent [Integer] Number of recent messages to keep at full detail
-      # @return [Array<RubyLLM::Message>] Compressed messages
-      def compress_tool_results(messages, keep_recent: 10)
-        messages.map.with_index do |msg, i|
-          # Keep recent messages at full detail
-          next msg if i >= messages.size - keep_recent
-
-          # Keep user/assistant messages (conversational flow is important)
-          next msg if [:user, :assistant].include?(msg.role)
-
-          # Compress old tool results
-          if msg.role == :tool
-            compress_tool_message(msg, age: messages.size - i)
-          else
-            msg
-          end
-        end
-      end
-
-      # Compress a single tool message based on age
-      #
-      # Progressive compression: older messages get compressed more.
-      # For re-runnable tools (Read, Grep, Glob, etc.), adds instruction to re-run if needed.
-      #
-      # @param msg [RubyLLM::Message] Tool message to compress
-      # @param age [Integer] How many messages ago (higher = older)
-      # @return [RubyLLM::Message] Compressed message
-      def compress_tool_message(msg, age:)
-        content = msg.content.to_s
-
-        # Progressive compression based on age
-        max_length = case age
-        when 0..10   then return msg           # Recent: keep full detail
-        when 11..20  then 1000                 # Medium age: light compression
-        when 21..40  then 500                  # Old: moderate compression
-        when 41..60  then 200                  # Very old: heavy compression
-        else              100                  # Ancient: minimal summary
-        end
-
-        return msg if content.length <= max_length
-
-        # Compress while preserving structure
-        compressed = content.slice(0, max_length)
-        truncated_chars = content.length - max_length
-        compressed += "\n...[#{truncated_chars} chars truncated for context management]"
-
-        # Detect if this is a re-runnable tool and add helpful instruction
-        tool_name = detect_tool_name(content)
-        if rerunnable_tool?(tool_name)
-          compressed += "\n\n💡 If you need the full output, re-run the #{tool_name} tool with the same parameters."
-        end
-
-        RubyLLM::Message.new(
-          role: :tool,
-          content: compressed,
-          tool_call_id: msg.tool_call_id,
-        )
-      end
-
-      # Detect tool name from content
-      #
-      # @param content [String] Tool result content
-      # @return [String, nil] Tool name or nil
-      def detect_tool_name(content)
-        # Many tool results start with patterns we can detect
-        case content
-        when /^\s*\d+→/ # Line numbers (Read, MemoryRead)
-          content.include?("memory://") ? "MemoryRead" : "Read"
-        when /^Memory entries matching/ # MemoryGlob
-          "MemoryGlob"
-        when /^Found \d+ files? matching/ # Glob
-          "Glob"
-        when /matches in \d+ files?|No matches found/ # Grep, MemoryGrep
-          content.include?("memory://") ? "MemoryGrep" : "Grep"
-        when %r{^Stored at memory://} # MemoryWrite (not re-runnable but identifiable)
-          "MemoryWrite"
-        when %r{^Deleted memory://} # MemoryDelete
-          "MemoryDelete"
-        end
-      end
-
-      # Check if a tool is re-runnable (idempotent, can get same data again)
-      #
-      # @param tool_name [String, nil] Tool name
-      # @return [Boolean] True if tool can be re-run safely
-      def rerunnable_tool?(tool_name)
-        return false if tool_name.nil?
-
-        # These tools are idempotent - re-running gives same/current data
-        ["Read", "MemoryRead", "Grep", "MemoryGrep", "Glob", "MemoryGlob"].include?(tool_name)
-      end
-
-      # Automatically compress messages when context threshold is hit
-      #
-      # This is called automatically when context usage crosses 60% threshold.
-      # Returns compressed messages array for immediate use.
-      #
-      # @param messages [Array<RubyLLM::Message>] Current message array
-      # @param keep_recent [Integer] Number of recent messages to keep full
-      # @return [Array<RubyLLM::Message>] Compressed messages
-      def auto_compress_on_threshold(messages, keep_recent: 10)
-        return messages if @compression_applied
-
-        # Mark as applied to avoid compressing multiple times
-        @compression_applied = true
-
-        compress_tool_results(messages, keep_recent: keep_recent)
-      end
-
-      # Reset compression flag (when conversation is reset)
-      #
-      # @return [void]
-      def reset_compression
-        @compression_applied = false
-      end
-
-      # Future: Detect if context is becoming bloated
-      #
-      # @param messages [Array<RubyLLM::Message>] Messages to analyze
-      # @param threshold [Float] Bloat threshold (0.0-1.0)
-      # @return [Hash] Bloat analysis with recommendations
-      def analyze_context_bloat(messages, threshold: 0.7)
-        # TODO: Implement when needed
-        { bloated: false, recommendations: [] }
-      end
-    end
-  end
-end