swarm_sdk 2.1.3 → 2.3.0

data/lib/swarm_sdk/configuration.rb

@@ -1,17 +1,42 @@
 # frozen_string_literal: true
 
 module SwarmSDK
+  # Configuration facade that delegates to Parser and Translator
+  #
+  # This class maintains the public API while internally delegating to:
+  # - Configuration::Parser - YAML parsing, validation, and normalization
+  # - Configuration::Translator - Translation to Swarm/Workflow DSL builders
+  #
+  # ## Public API (unchanged)
+  # - Configuration.load_file(path) - Load from file
+  # - Configuration.new(yaml_content, base_dir:) - Load from string
+  # - config.load_and_validate - Parse and validate
+  # - config.to_swarm(allow_filesystem_tools:) - Convert to Swarm/Workflow
+  # - config.agent_names - Get list of agent names
+  # - config.connections_for(agent_name) - Get delegation targets
+  #
+  # ## Architecture
+  # The facade pattern keeps backward compatibility while separating concerns:
+  # - Parser handles all YAML parsing and validation logic
+  # - Translator handles all DSL builder translation logic
+  # - Configuration delegates to both, exposing parsed data via attr_readers
   class Configuration
-    ENV_VAR_WITH_DEFAULT_PATTERN = /\$\{([^:}]+)(:=([^}]*))?\}/
-
-    attr_reader :swarm_name, :lead_agent, :agents, :all_agents_config, :swarm_hooks, :all_agents_hooks, :scratchpad_enabled
+    attr_reader :config_type,
+      :swarm_name,
+      :swarm_id,
+      :lead_agent,
+      :start_node,
+      :agents,
+      :all_agents_config,
+      :swarm_hooks,
+      :all_agents_hooks,
+      :scratchpad_enabled,
+      :nodes,
+      :external_swarms
 
     class << self
       # Load configuration from YAML file
       #
-      # Convenience method that reads the file and uses the file's directory
-      # as the base directory for resolving agent file paths.
-      #
       # @param path [String, Pathname] Path to YAML configuration file
       # @return [Configuration] Validated configuration instance
       # @raise [ConfigurationError] If file not found or invalid
@@ -41,30 +66,24 @@ module SwarmSDK
 
       @yaml_content = yaml_content
       @base_dir = Pathname.new(base_dir).expand_path
-      @agents = {}
-      @all_agents_config = {} # Settings applied to all agents
-      @swarm_hooks = {} # Swarm-level hooks (swarm_start, swarm_stop)
-      @all_agents_hooks = {} # Hooks applied to all agents
+      @parser = nil
+      @translator = nil
     end
 
+    # Parse and validate YAML configuration
+    #
+    # Delegates to Parser for all parsing logic, then syncs parsed data
+    # to instance variables for backward compatibility.
+    #
+    # @return [self]
     def load_and_validate
-      @config = YAML.safe_load(@yaml_content, permitted_classes: [Symbol], aliases: true)
+      @parser = Parser.new(@yaml_content, base_dir: @base_dir)
+      @parser.parse
 
-      unless @config.is_a?(Hash)
-        raise ConfigurationError, "Invalid YAML syntax: configuration must be a Hash"
-      end
+      # Sync parsed data to instance variables for backward compatibility
+      sync_from_parser
 
-      @config = Utils.symbolize_keys(@config)
-      interpolate_env_vars!(@config)
-      validate_version
-      load_all_agents_config
-      load_hooks_config
-      validate_swarm
-      load_agents
-      detect_circular_dependencies
       self
-    rescue Psych::SyntaxError => e
-      raise ConfigurationError, "Invalid YAML syntax: #{e.message}"
     end
 
     def agent_names
@@ -72,249 +91,45 @@ module SwarmSDK
     end
 
     def connections_for(agent_name)
-      @agents[agent_name]&.delegates_to || []
+      agent_config = @agents[agent_name]
+      return [] unless agent_config
+
+      delegates = agent_config[:delegates_to] || []
+      Array(delegates).map(&:to_sym)
     end
 
-    # Convert configuration to Swarm instance using Ruby API
+    # Convert configuration to Swarm or Workflow using appropriate builder
     #
-    # This method bridges YAML configuration to the Ruby API, making YAML
-    # a thin convenience layer over the programmatic interface.
+    # Delegates to Translator for all DSL translation logic.
     #
-    # @return [Swarm] Configured swarm instance
-    def to_swarm
-      swarm = Swarm.new(
-        name: @swarm_name,
-        global_concurrency: Swarm::DEFAULT_GLOBAL_CONCURRENCY,
-        default_local_concurrency: Swarm::DEFAULT_LOCAL_CONCURRENCY,
-        scratchpad_enabled: @scratchpad_enabled,
-      )
-
-      # Add all agents - pass definitions directly
-      @agents.each do |_name, agent_def|
-        swarm.add_agent(agent_def)
-      end
-
-      # Set lead agent
-      swarm.lead = @lead_agent
+    # @param allow_filesystem_tools [Boolean, nil] Whether to allow filesystem tools (nil uses global setting)
+    # @return [Swarm, Workflow] Configured swarm or workflow
+    def to_swarm(allow_filesystem_tools: nil)
+      raise ConfigurationError, "Configuration not loaded. Call load_and_validate first." unless @parser
 
-      swarm
+      @translator = Translator.new(@parser)
+      @translator.to_swarm(allow_filesystem_tools: allow_filesystem_tools)
     end
 
     private
 
-    def interpolate_env_vars!(obj)
-      case obj
-      when String
-        interpolate_env_string(obj)
-      when Hash
-        obj.transform_values! { |v| interpolate_env_vars!(v) }
-      when Array
-        obj.map! { |v| interpolate_env_vars!(v) }
-      else
-        obj
-      end
-    end
-
-    def interpolate_env_string(str)
-      str.gsub(ENV_VAR_WITH_DEFAULT_PATTERN) do |_match|
-        env_var = Regexp.last_match(1)
-        has_default = Regexp.last_match(2)
-        default_value = Regexp.last_match(3)
-
-        if ENV.key?(env_var)
-          ENV[env_var]
-        elsif has_default
-          default_value || ""
-        else
-          raise ConfigurationError, "Environment variable '#{env_var}' is not set"
-        end
-      end
-    end
-
-    def validate_version
-      version = @config[:version]
-      raise ConfigurationError, "Missing 'version' field in configuration" unless version
-      raise ConfigurationError, "SwarmSDK requires version: 2 configuration. Got version: #{version}" unless version == 2
-    end
-
-    def load_all_agents_config
-      return unless @config[:swarm]
-
-      @all_agents_config = @config[:swarm][:all_agents] || {}
-
-      # Convert disable_default_tools array elements to symbols
-      if @all_agents_config[:disable_default_tools].is_a?(Array)
-        @all_agents_config[:disable_default_tools] = @all_agents_config[:disable_default_tools].map(&:to_sym)
-      end
-    end
-
-    def load_hooks_config
-      return unless @config[:swarm]
-
-      # Load swarm-level hooks (only swarm_start, swarm_stop allowed)
-      @swarm_hooks = Utils.symbolize_keys(@config[:swarm][:hooks] || {})
-
-      # Load all_agents hooks (applied as swarm defaults)
-      if @config[:swarm][:all_agents]
-        @all_agents_hooks = Utils.symbolize_keys(@config[:swarm][:all_agents][:hooks] || {})
-      end
-    end
-
-    def validate_swarm
-      raise ConfigurationError, "Missing 'swarm' field in configuration" unless @config[:swarm]
-
-      swarm = @config[:swarm]
-      raise ConfigurationError, "Missing 'name' field in swarm configuration" unless swarm[:name]
-      raise ConfigurationError, "Missing 'agents' field in swarm configuration" unless swarm[:agents]
-      raise ConfigurationError, "Missing 'lead' field in swarm configuration" unless swarm[:lead]
-      raise ConfigurationError, "No agents defined" if swarm[:agents].empty?
-
-      @swarm_name = swarm[:name]
-      @lead_agent = swarm[:lead].to_sym # Convert to symbol for consistency
-      @scratchpad_enabled = swarm[:use_scratchpad].nil? ? true : swarm[:use_scratchpad] # Default: enabled
-    end
-
-    def load_agents
-      swarm_agents = @config[:swarm][:agents]
-
-      swarm_agents.each do |name, agent_config|
-        # Support three formats:
-        # 1. String: assistant: "agents/assistant.md" (file path)
-        # 2. Hash with agent_file: assistant: { agent_file: "..." }
-        # 3. Hash with inline definition: assistant: { description: "...", model: "..." }
-
-        if agent_config.is_a?(String)
-          # Format 1: Direct file path as string
-          file_path = agent_config
-          merged_config = merge_all_agents_config({})
-          @agents[name] = load_agent_from_file(name, file_path, merged_config)
-        else
-          # Format 2 or 3: Hash configuration
-          agent_config ||= {}
-
-          # Merge all_agents_config into agent config
-          # Agent-specific config overrides all_agents config
-          merged_config = merge_all_agents_config(agent_config)
-
-          @agents[name] = if agent_config[:agent_file]
-            # Format 2: Hash with agent_file key
-            load_agent_from_file(name, agent_config[:agent_file], merged_config)
-          else
-            # Format 3: Inline definition
-            Agent::Definition.new(name, merged_config)
-          end
-        end
-      end
-
-      unless @agents.key?(@lead_agent)
-        raise ConfigurationError, "Lead agent '#{@lead_agent}' not found in agents"
-      end
-    end
-
-    # Merge all_agents config with agent-specific config
-    # Agent config takes precedence over all_agents config
+    # Sync parsed data from Parser to instance variables
     #
-    # Merge strategy:
-    # - Arrays (tools, delegates_to): Concatenate
-    # - Hashes (parameters, headers): Merge (agent values override)
-    # - Scalars (model, provider, base_url, timeout, coding_agent): Agent overrides
-    #
-    # @param agent_config [Hash] Agent-specific configuration
-    # @return [Hash] Merged configuration
-    def merge_all_agents_config(agent_config)
-      merged = @all_agents_config.dup
-
-      # For arrays, concatenate
-      # For hashes, merge (agent values override)
-      # For scalars, agent value overrides
-      agent_config.each do |key, value|
-        case key
-        when :tools
-          # Concatenate tools: all_agents.tools + agent.tools
-          merged[:tools] = Array(merged[:tools]) + Array(value)
-        when :delegates_to
-          # Concatenate delegates_to
-          merged[:delegates_to] = Array(merged[:delegates_to]) + Array(value)
-        when :parameters
-          # Merge parameters: all_agents.parameters + agent.parameters
-          # Agent values override all_agents values for same keys
-          merged[:parameters] = (merged[:parameters] || {}).merge(value || {})
-        when :headers
-          # Merge headers: all_agents.headers + agent.headers
-          # Agent values override all_agents values for same keys
-          merged[:headers] = (merged[:headers] || {}).merge(value || {})
-        when :disable_default_tools
-          # Convert array elements to symbols if it's an array
-          merged[key] = value.is_a?(Array) ? value.map(&:to_sym) : value
-        else
-          # For everything else (model, provider, base_url, timeout, coding_agent, etc.),
-          # agent value overrides all_agents value
-          merged[key] = value
-        end
-      end
-
-      # Pass all_agents permissions as default_permissions for backward compat with AgentDefinition
-      if @all_agents_config[:permissions]
-        merged[:default_permissions] = @all_agents_config[:permissions]
-      end
-
-      merged
-    end
-
-    def load_agent_from_file(name, file_path, merged_config)
-      agent_file_path = resolve_agent_file_path(file_path)
-
-      unless File.exist?(agent_file_path)
-        raise ConfigurationError, "Agent file not found: #{agent_file_path}"
-      end
-
-      content = File.read(agent_file_path)
-      # Parse markdown and merge with YAML config
-      agent_def_from_file = MarkdownParser.parse(content, name)
-
-      # Merge: YAML config overrides markdown file (YAML takes precedence)
-      # This allows YAML to override any settings from the markdown file
-      final_config = agent_def_from_file.to_h.compact.merge(merged_config.compact)
-
-      Agent::Definition.new(name, final_config)
-    rescue StandardError => e
-      raise ConfigurationError, "Error loading agent '#{name}' from file '#{file_path}': #{e.message}"
-    end
-
-    def resolve_agent_file_path(file_path)
-      return file_path if Pathname.new(file_path).absolute?
-
-      @base_dir.join(file_path).to_s
-    end
-
-    def detect_circular_dependencies
-      @agents.each_key do |agent_name|
-        visited = Set.new
-        path = []
-        detect_cycle_from(agent_name, visited, path)
-      end
-    end
-
-    def detect_cycle_from(agent_name, visited, path)
-      return if visited.include?(agent_name)
-
-      if path.include?(agent_name)
-        cycle_start = path.index(agent_name)
-        cycle = path[cycle_start..] + [agent_name]
-        raise CircularDependencyError, "Circular dependency detected: #{cycle.join(" -> ")}"
-      end
-
-      path.push(agent_name)
-      connections_for(agent_name).each do |connection|
-        connection_sym = connection.to_sym # Convert to symbol for lookup
-        unless @agents.key?(connection_sym)
-          raise ConfigurationError, "Agent '#{agent_name}' has connection to unknown agent '#{connection}'"
-        end
-
-        detect_cycle_from(connection_sym, visited, path)
-      end
-      path.pop
-      visited.add(agent_name)
+    # This maintains backward compatibility with code that accesses
+    # @config_type, @agents, etc. directly via attr_readers.
+    def sync_from_parser
+      @config_type = @parser.config_type
+      @swarm_name = @parser.swarm_name
+      @swarm_id = @parser.swarm_id
+      @lead_agent = @parser.lead_agent
+      @start_node = @parser.start_node
+      @agents = @parser.agents
+      @all_agents_config = @parser.all_agents_config
+      @swarm_hooks = @parser.swarm_hooks
+      @all_agents_hooks = @parser.all_agents_hooks
+      @external_swarms = @parser.external_swarms
+      @nodes = @parser.nodes
+      @scratchpad_enabled = @parser.scratchpad_mode # NOTE: attr_reader says scratchpad_enabled
     end
   end
 end

data/lib/swarm_sdk/context_compactor/token_counter.rb

@@ -17,9 +17,9 @@ module SwarmSDK
     #   total_tokens = TokenCounter.estimate_messages(messages)
     #
     class TokenCounter
-      # Average characters per token for different content types
-      CHARS_PER_TOKEN_PROSE = 4.0
-      CHARS_PER_TOKEN_CODE = 3.5
+      # Backward compatibility aliases - use Defaults module for new code
+      CHARS_PER_TOKEN_PROSE = Defaults::TokenEstimation::CHARS_PER_TOKEN_PROSE
+      CHARS_PER_TOKEN_CODE = Defaults::TokenEstimation::CHARS_PER_TOKEN_CODE
 
       class << self
         # Estimate tokens for a single message

data/lib/swarm_sdk/context_compactor.rb

@@ -58,7 +58,7 @@ module SwarmSDK
     # @return [ContextCompactor::Metrics] Compression metrics
     def compact
       start_time = Time.now
-      original_messages = @chat.messages.dup
+      original_messages = @chat.messages
 
       # Emit compression_started event
       LogStream.emit(
@@ -308,7 +308,8 @@ module SwarmSDK
       response.content
     rescue StandardError => e
       # If summarization fails, create a simple fallback summary
-      RubyLLM.logger.warn("ContextCompactor: Summarization failed: #{e.message}")
+      LogStream.emit_error(e, source: "context_compactor", context: "generate_summary", agent: @agent_name)
+      RubyLLM.logger.debug("ContextCompactor: Summarization failed: #{e.message}")
 
       <<~FALLBACK
         ## Summary
@@ -322,19 +323,13 @@ module SwarmSDK
 
     # Replace messages in the chat
     #
-    # RubyLLM::Chat doesn't have a public API for replacing all messages,
-    # so we need to work with the internal messages array.
+    # Delegates to the Chat's replace_messages method which provides
+    # a safe abstraction over the internal message array.
     #
     # @param new_messages [Array<RubyLLM::Message>] New message array
     # @return [void]
     def replace_messages(new_messages)
-      # Clear existing messages
-      @chat.messages.clear
-
-      # Add new messages
-      new_messages.each do |msg|
-        @chat.messages << msg
-      end
+      @chat.replace_messages(new_messages)
     end
   end
 end

data/lib/swarm_sdk/context_management/builder.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module ContextManagement
+    # DSL for defining context management handlers
+    #
+    # This builder provides a clean, idiomatic way to register handlers for
+    # context warning thresholds. Handlers receive a rich context object
+    # with message manipulation methods.
+    #
+    # @example Basic usage
+    #   context_management do
+    #     on :warning_60 do |ctx|
+    #       ctx.compress_tool_results(keep_recent: 10)
+    #     end
+    #
+    #     on :warning_80 do |ctx|
+    #       ctx.prune_old_messages(keep_recent: 20)
+    #     end
+    #   end
+    #
+    # @example Progressive compression
+    #   context_management do
+    #     on :warning_60 do |ctx|
+    #       ctx.compress_tool_results(keep_recent: 15, truncate_to: 500)
+    #     end
+    #
+    #     on :warning_80 do |ctx|
+    #       ctx.prune_old_messages(keep_recent: 30)
+    #       ctx.compress_tool_results(keep_recent: 5, truncate_to: 200)
+    #     end
+    #
+    #     on :warning_90 do |ctx|
+    #       ctx.log_action("emergency_pruning", tokens_remaining: ctx.tokens_remaining)
+    #       ctx.prune_old_messages(keep_recent: 15)
+    #     end
+    #   end
+    class Builder
+      # Map semantic event names to threshold percentages
+      EVENT_MAP = {
+        warning_60: 60,
+        warning_80: 80,
+        warning_90: 90,
+      }.freeze
+
+      def initialize
+        @handlers = {} # { threshold => block }
+      end
+
+      # Register a handler for a context warning threshold
+      #
+      # Handlers take full responsibility for managing context at their threshold.
+      # When a handler is registered for a threshold, automatic compression is disabled
+      # for that threshold.
+      #
+      # @param event [Symbol] Event name (:warning_60, :warning_80, :warning_90)
+      # @yield [ContextManagement::Context] Context with message manipulation methods
+      # @return [void]
+      #
+      # @raise [ArgumentError] If event is unknown or block is missing
+      #
+      # @example Compress tool results at 60%
+      #   on :warning_60 do |ctx|
+      #     ctx.compress_tool_results(keep_recent: 10)
+      #   end
+      #
+      # @example Custom logic at 80%
+      #   on :warning_80 do |ctx|
+      #     if ctx.usage_percentage > 85
+      #       ctx.prune_old_messages(keep_recent: 10)
+      #     else
+      #       ctx.summarize_old_exchanges(older_than: 20)
+      #     end
+      #   end
+      #
+      # @example Log and prune at 90%
+      #   on :warning_90 do |ctx|
+      #     ctx.log_action("critical_threshold", remaining: ctx.tokens_remaining)
+      #     ctx.prune_old_messages(keep_recent: 10)
+      #   end
+      def on(event, &block)
+        threshold = EVENT_MAP[event]
+        raise ArgumentError, "Unknown event: #{event}. Valid events: #{EVENT_MAP.keys.join(", ")}" unless threshold
+        raise ArgumentError, "Block required for #{event}" unless block
+
+        @handlers[threshold] = block
+      end
+
+      # Build hook definitions from handlers
+      #
+      # Creates Hooks::Definition objects that wrap user blocks to provide
+      # rich context objects instead of raw Hooks::Context. Each handler
+      # becomes a hook for the :context_warning event.
+      #
+      # @return [Array<Hooks::Definition>] Hook definitions for :context_warning event
+      def build
+        @handlers.map do |threshold, user_block|
+          # Create a hook that filters by threshold and wraps context
+          Hooks::Definition.new(
+            event: :context_warning,
+            matcher: nil, # No tool matching needed
+            priority: 0,
+            proc: create_threshold_matcher(threshold, user_block),
+          )
+        end
+      end
+
+      private
+
+      # Create a proc that matches threshold and wraps context
+      #
+      # @param target_threshold [Integer] Threshold to match (60, 80, 90)
+      # @param user_block [Proc] User's handler block
+      # @return [Proc] Hook proc
+      def create_threshold_matcher(target_threshold, user_block)
+        proc do |hooks_context|
+          # Only execute for matching threshold
+          current_threshold = hooks_context.metadata[:threshold]
+          next unless current_threshold == target_threshold
+
+          # Wrap in rich context object
+          rich_context = Context.new(hooks_context)
+          user_block.call(rich_context)
+        end
+      end
+    end
+  end
+end