swarm_sdk 2.2.0 → 2.3.0

data/lib/swarm_sdk/configuration/parser.rb

@@ -0,0 +1,353 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  class Configuration
+    # Handles YAML parsing, validation, and normalization
+    #
+    # This class is responsible for:
+    # - Loading and parsing YAML content
+    # - Validating configuration structure
+    # - Normalizing data (symbolizing keys, env interpolation)
+    # - Detecting configuration type (swarm vs workflow)
+    # - Loading agents and nodes
+    # - Detecting circular dependencies
+    #
+    # After parsing, the parsed data can be translated to a Swarm/Workflow
+    # using the Translator class.
+    class Parser
+      ENV_VAR_WITH_DEFAULT_PATTERN = /\$\{([^:}]+)(:=([^}]*))?\}/
+
+      attr_reader :config_type,
+        :swarm_name,
+        :swarm_id,
+        :lead_agent,
+        :start_node,
+        :agents,
+        :all_agents_config,
+        :swarm_hooks,
+        :all_agents_hooks,
+        :scratchpad_mode,
+        :nodes,
+        :external_swarms
+
+      def initialize(yaml_content, base_dir:)
+        @yaml_content = yaml_content
+        @base_dir = Pathname.new(base_dir).expand_path
+        @config_type = nil
+        @swarm_id = nil
+        @swarm_name = nil
+        @lead_agent = nil
+        @start_node = nil
+        @agents = {}
+        @all_agents_config = {}
+        @swarm_hooks = {}
+        @all_agents_hooks = {}
+        @external_swarms = {}
+        @nodes = {}
+        @scratchpad_mode = :disabled
+      end
+
+      def parse
+        @config = YAML.safe_load(@yaml_content, permitted_classes: [Symbol], aliases: true)
+
+        unless @config.is_a?(Hash)
+          raise ConfigurationError, "Invalid YAML syntax: configuration must be a Hash"
+        end
+
+        @config = Utils.symbolize_keys(@config)
+        interpolate_env_vars!(@config)
+
+        validate_version
+        detect_and_validate_type
+        load_common_config
+        load_type_specific_config
+        load_agents
+        load_nodes if @config_type == :workflow
+        detect_circular_dependencies
+
+        self
+      rescue Psych::SyntaxError => e
+        raise ConfigurationError, "Invalid YAML syntax: #{e.message}"
+      end
+
+      def agent_names
+        @agents.keys
+      end
+
+      def connections_for(agent_name)
+        agent_config = @agents[agent_name]
+        return [] unless agent_config
+
+        delegates = agent_config[:delegates_to] || []
+        Array(delegates).map(&:to_sym)
+      end
+
+      attr_reader :base_dir
+
+      private
+
+      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 detect_and_validate_type
+        has_swarm = @config.key?(:swarm)
+        has_workflow = @config.key?(:workflow)
+
+        if has_swarm && has_workflow
+          raise ConfigurationError, "Cannot have both 'swarm:' and 'workflow:' keys. Use one or the other."
+        end
+
+        unless has_swarm || has_workflow
+          raise ConfigurationError, "Missing 'swarm:' or 'workflow:' key in configuration"
+        end
+
+        @config_type = has_swarm ? :swarm : :workflow
+        @root_config = @config[@config_type]
+      end
+
+      def load_common_config
+        raise ConfigurationError, "Missing 'name' field in #{@config_type} configuration" unless @root_config[:name]
+
+        @swarm_name = @root_config[:name]
+        @swarm_id = @root_config[:id]
+        @scratchpad_mode = parse_scratchpad_mode(@root_config[:scratchpad])
+
+        load_all_agents_config
+        load_hooks_config
+        load_external_swarms(@root_config[:swarms]) if @root_config[:swarms]
+      end
+
+      def load_type_specific_config
+        if @config_type == :swarm
+          load_swarm_config
+        else
+          load_workflow_config
+        end
+      end
+
+      def load_swarm_config
+        raise ConfigurationError, "Missing 'lead' field in swarm configuration" unless @root_config[:lead]
+        raise ConfigurationError, "Missing 'agents' field in swarm configuration" unless @root_config[:agents]
+
+        @lead_agent = @root_config[:lead].to_sym
+
+        if @root_config[:nodes] || @root_config[:start_node]
+          raise ConfigurationError, "Swarm configuration cannot have 'nodes' or 'start_node'. Use 'workflow:' key instead."
+        end
+      end
+
+      def load_workflow_config
+        raise ConfigurationError, "Missing 'start_node' field in workflow configuration" unless @root_config[:start_node]
+        raise ConfigurationError, "Missing 'nodes' field in workflow configuration" unless @root_config[:nodes]
+        raise ConfigurationError, "Missing 'agents' field in workflow configuration" unless @root_config[:agents]
+
+        @start_node = @root_config[:start_node].to_sym
+
+        if @root_config[:lead]
+          raise ConfigurationError, "Workflow configuration cannot have 'lead'. Use 'start_node' instead."
+        end
+      end
+
+      def load_all_agents_config
+        @all_agents_config = @root_config[:all_agents] || {}
+
+        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
+        @swarm_hooks = Utils.symbolize_keys(@root_config[:hooks] || {})
+
+        if @root_config[:all_agents]
+          @all_agents_hooks = Utils.symbolize_keys(@root_config[:all_agents][:hooks] || {})
+        end
+      end
+
+      def load_external_swarms(swarms_config)
+        @external_swarms = {}
+        swarms_config.each do |name, config|
+          source = if config[:file]
+            file_path = if config[:file].start_with?("/")
+              config[:file]
+            else
+              (@base_dir / config[:file]).to_s
+            end
+            { type: :file, value: file_path }
+          elsif config[:yaml]
+            { type: :yaml, value: config[:yaml] }
+          elsif config[:swarm]
+            inline_config = {
+              version: 2,
+              swarm: config[:swarm],
+            }
+            yaml_string = Utils.hash_to_yaml(inline_config)
+            { type: :yaml, value: yaml_string }
+          else
+            raise ConfigurationError, "Swarm '#{name}' must specify either 'file:', 'yaml:', or 'swarm:' (inline definition)"
+          end
+
+          @external_swarms[name.to_sym] = {
+            source: source,
+            keep_context: config.fetch(:keep_context, true),
+          }
+        end
+      end
+
+      def load_agents
+        swarm_agents = @root_config[:agents]
+        raise ConfigurationError, "No agents defined" if swarm_agents.empty?
+
+        swarm_agents.each do |name, agent_config|
+          parsed_config = if agent_config.nil?
+            {}
+          elsif agent_config.is_a?(String)
+            { agent_file: agent_config }
+          elsif agent_config.is_a?(Hash) && agent_config[:agent_file]
+            agent_config
+          else
+            agent_config || {}
+          end
+
+          if parsed_config[:agent_file].nil? && parsed_config[:description].nil?
+            raise ConfigurationError,
+              "Agent '#{name}' missing required 'description' field"
+          end
+
+          @agents[name] = parsed_config
+        end
+
+        if @config_type == :swarm
+          unless @agents.key?(@lead_agent)
+            raise ConfigurationError, "Lead agent '#{@lead_agent}' not found in agents"
+          end
+        end
+      end
+
+      def load_nodes
+        @nodes = Utils.symbolize_keys(@root_config[:nodes])
+
+        unless @nodes.key?(@start_node)
+          raise ConfigurationError, "start_node '#{@start_node}' not found in nodes"
+        end
+
+        @nodes.each do |node_name, node_config|
+          unless node_config.is_a?(Hash)
+            raise ConfigurationError, "Node '#{node_name}' must be a hash"
+          end
+
+          if node_config[:agents]
+            unless node_config[:agents].is_a?(Array)
+              raise ConfigurationError, "Node '#{node_name}' agents must be an array"
+            end
+
+            node_config[:agents].each do |agent_config|
+              unless agent_config.is_a?(Hash) && agent_config[:agent]
+                raise ConfigurationError,
+                  "Node '#{node_name}' agents must be hashes with 'agent' key"
+              end
+
+              agent_sym = agent_config[:agent].to_sym
+              unless @agents.key?(agent_sym)
+                raise ConfigurationError,
+                  "Node '#{node_name}' references undefined agent '#{agent_config[:agent]}'"
+              end
+            end
+          end
+
+          next unless node_config[:dependencies]
+          unless node_config[:dependencies].is_a?(Array)
+            raise ConfigurationError, "Node '#{node_name}' dependencies must be an array"
+          end
+
+          node_config[:dependencies].each do |dep|
+            dep_sym = dep.to_sym
+            unless @nodes.key?(dep_sym)
+              raise ConfigurationError,
+                "Node '#{node_name}' depends on undefined node '#{dep}'"
+            end
+          end
+        end
+      end
+
+      def parse_scratchpad_mode(value)
+        return :disabled if value.nil?
+
+        value = value.to_sym if value.is_a?(String)
+
+        case value
+        when :enabled, :disabled, :per_node
+          value
+        else
+          raise ConfigurationError,
+            "Invalid scratchpad mode: #{value.inspect}. Use :enabled, :per_node, or :disabled"
+        end
+      end
+
+      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 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
+
+          next if @external_swarms.key?(connection_sym)
+
+          unless @agents.key?(connection_sym)
+            raise ConfigurationError, "Agent '#{agent_name}' delegates to unknown target '#{connection}' (not a local agent or registered swarm)"
+          end
+
+          detect_cycle_from(connection_sym, visited, path)
+        end
+        path.pop
+        visited.add(agent_name)
+      end
+    end
+  end
+end

data/lib/swarm_sdk/configuration/translator.rb

@@ -0,0 +1,255 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  class Configuration
+    # Translates parsed configuration to Swarm/Workflow using DSL builders
+    #
+    # This class is responsible for:
+    # - Creating the appropriate builder (Swarm::Builder or Workflow::Builder)
+    # - Translating parsed configuration into DSL method calls
+    # - Building the final Swarm or Workflow instance
+    #
+    # Receives a parsed Configuration::Parser and converts it to runtime objects.
+    class Translator
+      def initialize(parser)
+        @parser = parser
+      end
+
+      def to_swarm(allow_filesystem_tools: nil)
+        builder = create_builder(allow_filesystem_tools)
+
+        translate_common_config(builder)
+        translate_type_specific_config(builder)
+        translate_agents(builder)
+        translate_hooks(builder)
+
+        builder.build_swarm
+      end
+
+      private
+
+      def create_builder(allow_filesystem_tools)
+        if @parser.config_type == :swarm
+          Swarm::Builder.new(allow_filesystem_tools: allow_filesystem_tools)
+        else
+          Workflow::Builder.new(allow_filesystem_tools: allow_filesystem_tools)
+        end
+      end
+
+      def translate_common_config(builder)
+        builder.id(@parser.swarm_id) if @parser.swarm_id
+        builder.name(@parser.swarm_name)
+        builder.scratchpad(@parser.scratchpad_mode)
+
+        if @parser.external_swarms&.any?
+          external_swarms = @parser.external_swarms
+          builder.swarms do
+            external_swarms.each do |name, config|
+              source = config[:source]
+              case source[:type]
+              when :file
+                register(name, file: source[:value], keep_context: config[:keep_context])
+              when :yaml
+                register(name, yaml: source[:value], keep_context: config[:keep_context])
+              else
+                raise ConfigurationError, "Unknown source type: #{source[:type]}"
+              end
+            end
+          end
+        end
+
+        translate_all_agents(builder) if @parser.all_agents_config.any?
+      end
+
+      def translate_type_specific_config(builder)
+        if @parser.config_type == :swarm
+          builder.lead(@parser.lead_agent)
+        else
+          builder.start_node(@parser.start_node)
+          translate_nodes(builder)
+        end
+      end
+
+      def translate_hooks(builder)
+        return if @parser.swarm_hooks.none?
+
+        @parser.swarm_hooks.each do |event, hook_specs|
+          Array(hook_specs).each do |spec|
+            if spec[:type] == "command"
+              builder.hook(event, command: spec[:command], timeout: spec[:timeout])
+            end
+          end
+        end
+      end
+
+      def translate_all_agents(builder)
+        all_agents_cfg = @parser.all_agents_config
+        all_agents_hks = @parser.all_agents_hooks
+
+        builder.all_agents do
+          tools(*all_agents_cfg[:tools]) if all_agents_cfg[:tools]&.any?
+          model(all_agents_cfg[:model]) if all_agents_cfg[:model]
+          provider(all_agents_cfg[:provider]) if all_agents_cfg[:provider]
+          base_url(all_agents_cfg[:base_url]) if all_agents_cfg[:base_url]
+          api_version(all_agents_cfg[:api_version]) if all_agents_cfg[:api_version]
+          timeout(all_agents_cfg[:timeout]) if all_agents_cfg[:timeout]
+          parameters(all_agents_cfg[:parameters]) if all_agents_cfg[:parameters]
+          headers(all_agents_cfg[:headers]) if all_agents_cfg[:headers]
+          coding_agent(all_agents_cfg[:coding_agent]) unless all_agents_cfg[:coding_agent].nil?
+          disable_default_tools(all_agents_cfg[:disable_default_tools]) unless all_agents_cfg[:disable_default_tools].nil?
+
+          if all_agents_hks.any?
+            all_agents_hks.each do |event, hook_specs|
+              Array(hook_specs).each do |spec|
+                matcher = spec[:matcher]
+                hook(event, matcher: matcher, command: spec[:command], timeout: spec[:timeout]) if spec[:type] == "command"
+              end
+            end
+          end
+
+          self.permissions_hash = all_agents_cfg[:permissions] if all_agents_cfg[:permissions]
+        end
+      end
+
+      def translate_agents(builder)
+        @parser.agents.each do |name, agent_config|
+          translate_agent(builder, name, agent_config)
+        rescue ConfigurationError => e
+          raise ConfigurationError, "Error in #{@parser.config_type}.agents.#{name}: #{e.message}"
+        end
+      end
+
+      def translate_agent(builder, name, config)
+        if config[:agent_file]
+          agent_file_path = resolve_agent_file_path(config[:agent_file])
+
+          unless File.exist?(agent_file_path)
+            raise ConfigurationError, "Agent file not found: #{agent_file_path}"
+          end
+
+          content = File.read(agent_file_path)
+          overrides = config.except(:agent_file)
+
+          if overrides.any?
+            builder.agent(name, content, &create_agent_config_block(overrides))
+          else
+            builder.agent(name, content)
+          end
+        else
+          builder.agent(name, &create_agent_config_block(config))
+        end
+      rescue StandardError => e
+        raise ConfigurationError, "Error loading agent '#{name}': #{e.message}"
+      end
+
+      def create_agent_config_block(config)
+        proc do
+          description(config[:description]) if config[:description]
+          model(config[:model]) if config[:model]
+          provider(config[:provider]) if config[:provider]
+          base_url(config[:base_url]) if config[:base_url]
+          api_version(config[:api_version]) if config[:api_version]
+          context_window(config[:context_window]) if config[:context_window]
+          system_prompt(config[:system_prompt]) if config[:system_prompt]
+          directory(config[:directory]) if config[:directory]
+          timeout(config[:timeout]) if config[:timeout]
+          parameters(config[:parameters]) if config[:parameters]
+          headers(config[:headers]) if config[:headers]
+          coding_agent(config[:coding_agent]) unless config[:coding_agent].nil?
+          bypass_permissions(config[:bypass_permissions]) if config[:bypass_permissions]
+          disable_default_tools(config[:disable_default_tools]) unless config[:disable_default_tools].nil?
+          shared_across_delegations(config[:shared_across_delegations]) unless config[:shared_across_delegations].nil?
+
+          if config[:tools]&.any?
+            tool_names = config[:tools].map { |t| t.is_a?(Hash) ? t[:name] : t }
+            tools(*tool_names)
+          end
+
+          delegates_to(*config[:delegates_to]) if config[:delegates_to]&.any?
+
+          config[:mcp_servers]&.each do |server|
+            mcp_server(server[:name], **server.except(:name))
+          end
+
+          config[:hooks]&.each do |event, hook_specs|
+            Array(hook_specs).each do |spec|
+              matcher = spec[:matcher]
+              hook(event, matcher: matcher, command: spec[:command], timeout: spec[:timeout]) if spec[:type] == "command"
+            end
+          end
+
+          # Translate context_management YAML config to DSL
+          if config[:context_management]
+            ctx_mgmt_config = config[:context_management]
+            context_management do
+              ctx_mgmt_config.each do |event_name, handler_cfg|
+                # Capture handler_cfg in closure for each threshold
+                captured_config = handler_cfg
+                on(event_name.to_sym) do |ctx|
+                  action = captured_config[:action]&.to_s
+
+                  case action
+                  when "compress_tool_results"
+                    ctx.compress_tool_results(
+                      keep_recent: captured_config[:keep_recent] || 10,
+                      truncate_to: captured_config[:truncate_to] || 200,
+                    )
+                  when "prune_old_messages"
+                    ctx.prune_old_messages(keep_recent: captured_config[:keep_recent] || 20)
+                  when "log_warning"
+                    ctx.log_action("threshold_warning", threshold: ctx.threshold)
+                  else
+                    raise ConfigurationError, "Unknown context_management action: #{action}"
+                  end
+                end
+              end
+            end
+          end
+
+          # Let plugins handle their YAML config translation
+          # This removes SDK knowledge of plugin-specific configuration
+          PluginRegistry.all.each do |plugin|
+            plugin.translate_yaml_config(self, config)
+          end
+
+          self.permissions_hash = config[:permissions] if config[:permissions]
+        end
+      end
+
+      def translate_nodes(builder)
+        @parser.nodes.each do |node_name, node_config|
+          builder.node(node_name) do
+            node_config[:agents]&.each do |agent_config|
+              agent_name = agent_config[:agent].to_sym
+              delegates = agent_config[:delegates_to] || []
+              reset_ctx = agent_config.key?(:reset_context) ? agent_config[:reset_context] : true
+              tools_override = agent_config[:tools]
+
+              agent_cfg = agent(agent_name, reset_context: reset_ctx)
+              agent_cfg = agent_cfg.delegates_to(*delegates) if delegates.any?
+              agent_cfg.tools(*tools_override) if tools_override
+            end
+
+            depends_on(*node_config[:dependencies]) if node_config[:dependencies]&.any?
+
+            lead(node_config[:lead].to_sym) if node_config[:lead]
+
+            if node_config[:input_command]
+              input_command(node_config[:input_command], timeout: node_config[:input_timeout] || 60)
+            end
+
+            if node_config[:output_command]
+              output_command(node_config[:output_command], timeout: node_config[:output_timeout] || 60)
+            end
+          end
+        end
+      end
+
+      def resolve_agent_file_path(file_path)
+        return file_path if Pathname.new(file_path).absolute?
+
+        @parser.base_dir.join(file_path).to_s
+      end
+    end
+  end
+end