swarm_sdk 2.0.0.pre.2 → 2.0.0

data/lib/swarm_sdk/swarm/all_agents_builder.rb

@@ -3,17 +3,77 @@
 module SwarmSDK
   class Swarm
     # AllAgentsBuilder for configuring settings that apply to all agents
+    #
+    # Settings configured here are applied to ALL agents, but can be overridden
+    # at the agent level. This is useful for shared configuration like:
+    # - Common provider/base_url (all agents use same proxy)
+    # - Shared timeout settings
+    # - Global permissions
+    #
+    # @example
+    #   all_agents do
+    #     provider :openai
+    #     base_url "http://proxy.com/v1"
+    #     timeout 180
+    #     tools :Read, :Write
+    #     coding_agent false
+    #   end
     class AllAgentsBuilder
-      attr_reader :hooks, :permissions_config
+      attr_reader :hooks, :permissions_config, :tools_list
 
       def initialize
         @tools_list = []
         @hooks = []
         @permissions_config = {}
+        @model = nil
+        @provider = nil
+        @base_url = nil
+        @api_version = nil
+        @timeout = nil
+        @parameters = nil
+        @headers = nil
+        @coding_agent = nil
       end
 
-      # Get tools list
-      attr_reader :tools_list
+      # Set model for all agents
+      def model(model_name)
+        @model = model_name
+      end
+
+      # Set provider for all agents
+      def provider(provider_name)
+        @provider = provider_name
+      end
+
+      # Set base URL for all agents
+      def base_url(url)
+        @base_url = url
+      end
+
+      # Set API version for all agents
+      def api_version(version)
+        @api_version = version
+      end
+
+      # Set timeout for all agents
+      def timeout(seconds)
+        @timeout = seconds
+      end
+
+      # Set parameters for all agents
+      def parameters(params)
+        @parameters = params
+      end
+
+      # Set headers for all agents
+      def headers(header_hash)
+        @headers = header_hash
+      end
+
+      # Set coding_agent flag for all agents
+      def coding_agent(enabled)
+        @coding_agent = enabled
+      end
 
       # Add tools that all agents will have
       def tools(*tool_names)
@@ -57,6 +117,24 @@ module SwarmSDK
       def permissions(&block)
         @permissions_config = PermissionsBuilder.build(&block)
       end
+
+      # Convert to hash for merging with agent configs
+      #
+      # @return [Hash] Configuration hash
+      def to_h
+        {
+          model: @model,
+          provider: @provider,
+          base_url: @base_url,
+          api_version: @api_version,
+          timeout: @timeout,
+          parameters: @parameters,
+          headers: @headers,
+          coding_agent: @coding_agent,
+          tools: @tools_list,
+          permissions: @permissions_config,
+        }.compact
+      end
     end
   end
 end

data/lib/swarm_sdk/swarm/builder.rb

@@ -50,6 +50,8 @@ module SwarmSDK
         @agents = {}
         @all_agents_config = nil
         @swarm_hooks = []
+        @nodes = {}
+        @start_node = nil
       end
 
       # Set swarm name
@@ -62,22 +64,47 @@ module SwarmSDK
         @lead_agent = agent_name
       end
 
-      # Define an agent with fluent API
+      # Define an agent with fluent API or load from markdown content
       #
-      # @example
+      # Supports two forms:
+      # 1. Inline DSL: agent :name do ... end
+      # 2. Markdown content: agent :name, <<~MD ... MD
+      #
+      # The name parameter is always required. If the markdown has a name field
+      # in frontmatter, it will be replaced by the name parameter.
+      #
+      # @example Inline DSL
       #   agent :backend do
       #     model "gpt-5"
-      #     prompt "You build APIs"
+      #     system_prompt "You build APIs"
       #     tools :Read, :Write
       #
       #     hook :pre_tool_use, matcher: "Bash" do |ctx|
       #       # Inline validation logic!
       #     end
       #   end
-      def agent(name, &block)
-        builder = Agent::Builder.new(name)
-        builder.instance_eval(&block)
-        @agents[name] = builder
+      #
+      # @example Markdown content
+      #   agent :backend, <<~MD
+      #     ---
+      #     description: "Backend developer"
+      #     model: "gpt-4"
+      #     ---
+      #
+      #     You build APIs.
+      #   MD
+      def agent(name, content = nil, &block)
+        # Case 1: agent :name, <<~MD (name + markdown content)
+        if content.is_a?(String) && !block_given? && markdown_content?(content)
+          load_agent_from_markdown(content, name)
+        # Case 2: agent :name do ... end (inline DSL)
+        elsif block_given?
+          builder = Agent::Builder.new(name)
+          builder.instance_eval(&block)
+          @agents[name] = builder
+        else
+          raise ArgumentError, "Invalid agent definition. Use: agent :name { ... } OR agent :name, <<~MD ... MD"
+        end
       end
 
       # Add swarm-level hook (swarm_start, swarm_stop only)
@@ -114,21 +141,111 @@ module SwarmSDK
         @all_agents_config = builder
       end
 
-      # Build the actual Swarm instance
+      # Define a node (mini-swarm execution stage)
+      #
+      # Nodes enable multi-stage workflows where different agent teams
+      # collaborate in sequence. Each node is an independent swarm execution.
+      #
+      # @param name [Symbol] Node name
+      # @yield Block for node configuration
+      # @return [void]
+      #
+      # @example Solo agent node
+      #   node :planning do
+      #     agent(:architect)
+      #   end
+      #
+      # @example Multi-agent node with delegation
+      #   node :implementation do
+      #     agent(:backend).delegates_to(:tester, :database)
+      #     agent(:tester).delegates_to(:database)
+      #     agent(:database)
+      #     after :planning
+      #   end
+      def node(name, &block)
+        builder = Node::Builder.new(name)
+        builder.instance_eval(&block)
+        @nodes[name] = builder
+      end
+
+      # Set the starting node for workflow execution
+      #
+      # Required when nodes are defined. Specifies which node to execute first.
+      #
+      # @param name [Symbol] Name of starting node
+      # @return [void]
+      #
+      # @example
+      #   start_node :planning
+      def start_node(name)
+        @start_node = name.to_sym
+      end
+
+      # Build the actual Swarm instance or NodeOrchestrator
       def build_swarm
         raise ConfigurationError, "Swarm name not set. Use: name 'My Swarm'" unless @swarm_name
-        raise ConfigurationError, "Lead agent not set. Use: lead :agent_name" unless @lead_agent
-        raise ConfigurationError, "No agents defined. Use: agent :name { ... }" if @agents.empty?
 
+        # Check if nodes are defined
+        if @nodes.any?
+          # Node-based workflow (agents optional for agent-less workflows)
+          build_node_orchestrator
+        else
+          # Traditional single-swarm execution (requires agents and lead)
+          raise ConfigurationError, "No agents defined. Use: agent :name { ... }" if @agents.empty?
+          raise ConfigurationError, "Lead agent not set. Use: lead :agent_name" unless @lead_agent
+
+          build_single_swarm
+        end
+      end
+
+      private
+
+      # Check if a string is markdown content (has frontmatter)
+      #
+      # @param str [String] String to check
+      # @return [Boolean] true if string contains markdown frontmatter
+      def markdown_content?(str)
+        str.start_with?("---") || str.include?("\n---\n")
+      end
+
+      # Load an agent from markdown content
+      #
+      # Returns a hash of the agent config (not a Definition yet) so that
+      # all_agents config can be applied later in the build process.
+      #
+      # @param content [String] Markdown content with frontmatter
+      # @param name_override [Symbol, nil] Optional name to override frontmatter name
+      # @return [void]
+      def load_agent_from_markdown(content, name_override = nil)
+        # Parse markdown content - will extract name from frontmatter if not overridden
+        definition = MarkdownParser.parse(content, name_override)
+
+        # Store the config hash (not Definition) so all_agents can be applied
+        # We'll wrap this in a special marker so we know it came from markdown
+        @agents[definition.name] = { __file_config__: definition.to_h }
+      end
+
+      # Build a traditional single-swarm execution
+      #
+      # @return [Swarm] Configured swarm instance
+      def build_single_swarm
         # Create swarm using SDK
         swarm = Swarm.new(name: @swarm_name)
 
-        # Merge all_agents config into each agent
+        # Merge all_agents config into each agent (including file-loaded ones)
         merge_all_agents_config_into_agents if @all_agents_config
 
         # Build definitions and add to swarm
-        @agents.each do |_agent_name, agent_builder|
-          definition = agent_builder.to_definition
+        # Handle both Agent::Builder (inline DSL) and file configs (from files)
+        @agents.each do |agent_name, agent_builder_or_config|
+          definition = if agent_builder_or_config.is_a?(Hash) && agent_builder_or_config.key?(:__file_config__)
+            # File-loaded agent config (with all_agents merged)
+            Agent::Definition.new(agent_name, agent_builder_or_config[:__file_config__])
+          else
+            # Builder object (from inline DSL) - convert to definition
+            agent_builder_or_config.to_definition
+          end
+
           swarm.add_agent(definition)
         end
 
@@ -154,24 +271,172 @@ module SwarmSDK
         swarm
       end
 
-      private
+      # Build a node-based workflow orchestrator
+      #
+      # @return [NodeOrchestrator] Configured orchestrator
+      def build_node_orchestrator
+        raise ConfigurationError, "start_node required when nodes are defined. Use: start_node :name" unless @start_node
+
+        # Merge all_agents config into each agent (applies to all nodes)
+        merge_all_agents_config_into_agents if @all_agents_config
+
+        # Build agent definitions
+        # Handle both Agent::Builder (inline DSL) and file configs (from files)
+        agent_definitions = {}
+        @agents.each do |agent_name, agent_builder_or_config|
+          agent_definitions[agent_name] = if agent_builder_or_config.is_a?(Hash) && agent_builder_or_config.key?(:__file_config__)
+            # File-loaded agent config (with all_agents merged)
+            Agent::Definition.new(agent_name, agent_builder_or_config[:__file_config__])
+          else
+            # Builder object (from inline DSL) - convert to definition
+            agent_builder_or_config.to_definition
+          end
+        end
+
+        # Create node orchestrator
+        NodeOrchestrator.new(
+          swarm_name: @swarm_name,
+          agent_definitions: agent_definitions,
+          nodes: @nodes,
+          start_node: @start_node,
+        )
+      end
 
       # Merge all_agents configuration into each agent
+      #
+      # All_agents values are used as defaults - agent-specific values override.
+      # This applies to both inline DSL agents (Builder) and file-loaded agents (config hash).
+      #
+      # @return [void]
       def merge_all_agents_config_into_agents
         return unless @all_agents_config
 
-        @agents.each_value do |agent_builder|
-          # Merge tools (prepend all_agents tools)
-          all_agents_tools = @all_agents_config.tools_list
-          agent_builder.prepend_tools(*all_agents_tools) if all_agents_tools.any?
+        all_agents_hash = @all_agents_config.to_h
+
+        @agents.each_value do |agent_builder_or_config|
+          if agent_builder_or_config.is_a?(Hash) && agent_builder_or_config.key?(:__file_config__)
+            # File-loaded agent - merge into the config hash
+            file_config = agent_builder_or_config[:__file_config__]
+
+            # Merge all_agents into file config (file config overrides)
+            # Use same merge strategy as Configuration class
+            merged_config = merge_all_agents_into_config(all_agents_hash, file_config)
 
-          # Pass all_agents permissions as default_permissions
-          if @all_agents_config.permissions_config.any?
-            agent_builder.default_permissions = @all_agents_config.permissions_config
+            # Update the stored config
+            agent_builder_or_config[:__file_config__] = merged_config
+          else
+            # Builder object (inline DSL agent)
+            agent_builder = agent_builder_or_config
+
+            # Apply all_agents defaults that haven't been set at agent level
+            # Agent values override all_agents values
+            apply_all_agents_defaults(agent_builder, all_agents_hash)
+
+            # Merge tools (prepend all_agents tools)
+            all_agents_tools = @all_agents_config.tools_list
+            agent_builder.prepend_tools(*all_agents_tools) if all_agents_tools.any?
+
+            # Pass all_agents permissions as default_permissions
+            if @all_agents_config.permissions_config.any?
+              agent_builder.default_permissions = @all_agents_config.permissions_config
+            end
           end
         end
       end
 
+      # Merge all_agents config into file-loaded agent config
+      #
+      # Follows same merge strategy as Configuration class:
+      # - Arrays (tools, delegates_to): Concatenate (all_agents + file)
+      # - Hashes (parameters, headers): Merge (file values override)
+      # - Scalars (model, provider, etc.): File overrides
+      #
+      # @param all_agents_hash [Hash] All_agents configuration
+      # @param file_config [Hash] File-loaded agent configuration
+      # @return [Hash] Merged configuration
+      def merge_all_agents_into_config(all_agents_hash, file_config)
+        merged = all_agents_hash.dup
+
+        file_config.each do |key, value|
+          case key
+          when :tools
+            # Concatenate tools: all_agents.tools + file.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: file values override all_agents
+            merged[:parameters] = (merged[:parameters] || {}).merge(value || {})
+          when :headers
+            # Merge headers: file values override all_agents
+            merged[:headers] = (merged[:headers] || {}).merge(value || {})
+          else
+            # For everything else, file value overrides all_agents value
+            merged[key] = value
+          end
+        end
+
+        # Pass all_agents permissions as default_permissions
+        if all_agents_hash[:permissions] && !merged[:default_permissions]
+          merged[:default_permissions] = all_agents_hash[:permissions]
+        end
+
+        merged
+      end
+
+      # Apply all_agents defaults to an agent builder
+      #
+      # Only sets values that haven't been explicitly set at the agent level.
+      # This implements the override semantics: agent values take precedence.
+      #
+      # @param agent_builder [Agent::Builder] The agent builder to configure
+      # @param all_agents_hash [Hash] All_agents configuration
+      # @return [void]
+      def apply_all_agents_defaults(agent_builder, all_agents_hash)
+        # Model: only set if agent hasn't explicitly set it
+        if all_agents_hash[:model] && !agent_builder.model_set?
+          agent_builder.model(all_agents_hash[:model])
+        end
+
+        # Provider: only set if agent hasn't set it
+        if all_agents_hash[:provider] && !agent_builder.provider_set?
+          agent_builder.provider(all_agents_hash[:provider])
+        end
+
+        # Base URL: only set if agent hasn't set it
+        if all_agents_hash[:base_url] && !agent_builder.base_url_set?
+          agent_builder.base_url(all_agents_hash[:base_url])
+        end
+
+        # API Version: only set if agent hasn't set it
+        if all_agents_hash[:api_version] && !agent_builder.api_version_set?
+          agent_builder.api_version(all_agents_hash[:api_version])
+        end
+
+        # Timeout: only set if agent hasn't set it
+        if all_agents_hash[:timeout] && !agent_builder.timeout_set?
+          agent_builder.timeout(all_agents_hash[:timeout])
+        end
+
+        # Parameters: merge (all_agents + agent, agent values override)
+        if all_agents_hash[:parameters]
+          merged_params = all_agents_hash[:parameters].merge(agent_builder.parameters)
+          agent_builder.parameters(merged_params)
+        end
+
+        # Headers: merge (all_agents + agent, agent values override)
+        if all_agents_hash[:headers]
+          merged_headers = all_agents_hash[:headers].merge(agent_builder.headers)
+          agent_builder.headers(merged_headers)
+        end
+
+        # Coding_agent: only set if agent hasn't set it
+        if !all_agents_hash[:coding_agent].nil? && !agent_builder.coding_agent_set?
+          agent_builder.coding_agent(all_agents_hash[:coding_agent])
+        end
+      end
+
       def apply_swarm_hook(swarm, config)
         event = config[:event]
 

data/lib/swarm_sdk/swarm/tool_configurator.rb

@@ -194,6 +194,7 @@ module SwarmSDK
             agent_name: agent_name,
             swarm: @swarm,
             hook_registry: @hook_registry,
+            delegating_chat: chat,
           )
 
           chat.with_tool(tool)

data/lib/swarm_sdk/swarm.rb

@@ -254,9 +254,6 @@ module SwarmSDK
       # Lazy initialization of agents (with optional logging)
       initialize_agents unless @agents_initialized
 
-      # Freeze log collector to make it fiber-safe before Async execution
-      LogCollector.freeze! if block_given?
-
       # Execution loop (supports reprompting)
       result = nil
       swarm_stop_triggered = false
@@ -359,9 +356,26 @@ module SwarmSDK
 
       # Cleanup MCP clients after execution
       cleanup
-      # Reset logging state for next execution
-      LogCollector.reset!
-      LogStream.reset!
+
+      # Reset logging state for next execution if we set it up
+      #
+      # IMPORTANT: Only reset if we set up logging (block_given? == true).
+      # When this swarm is a mini-swarm within a NodeOrchestrator workflow,
+      # the orchestrator manages LogCollector and we don't set up logging.
+      #
+      # Flow in NodeOrchestrator:
+      # 1. NodeOrchestrator sets up LogCollector + LogStream (no block given to mini-swarms)
+      # 2. Each mini-swarm executes without logging block (block_given? == false)
+      # 3. Each mini-swarm skips reset (didn't set up logging)
+      # 4. NodeOrchestrator resets once at the very end
+      #
+      # Flow in standalone swarm / interactive REPL:
+      # 1. Swarm.execute sets up LogCollector + LogStream (block given)
+      # 2. Swarm.execute resets in ensure block (cleanup for next call)
+      if block_given?
+        LogCollector.reset!
+        LogStream.reset!
+      end
     end
 
     # Get an agent chat instance by name
@@ -395,6 +409,57 @@ module SwarmSDK
       @agent_definitions.keys
     end
 
+    # Validate swarm configuration and return warnings
+    #
+    # This performs lightweight validation checks without creating agents.
+    # Useful for displaying configuration warnings before execution.
+    #
+    # @return [Array<Hash>] Array of warning hashes from all agent definitions
+    #
+    # @example
+    #   swarm = Swarm.load("config.yml")
+    #   warnings = swarm.validate
+    #   warnings.each do |warning|
+    #     puts "⚠️  #{warning[:agent]}: #{warning[:model]} not found"
+    #   end
+    def validate
+      @agent_definitions.flat_map { |_name, definition| definition.validate }
+    end
+
+    # Emit validation warnings as log events
+    #
+    # This validates all agent definitions and emits any warnings as
+    # model_lookup_warning events through LogStream. Useful for emitting
+    # warnings before execution starts (e.g., in REPL after welcome screen).
+    #
+    # Requires LogStream.emitter to be set.
+    #
+    # @return [Array<Hash>] The validation warnings that were emitted
+    #
+    # @example
+    #   LogCollector.on_log { |event| puts event }
+    #   LogStream.emitter = LogCollector
+    #   swarm.emit_validation_warnings
+    def emit_validation_warnings
+      warnings = validate
+
+      warnings.each do |warning|
+        case warning[:type]
+        when :model_not_found
+          LogStream.emit(
+            type: "model_lookup_warning",
+            agent: warning[:agent],
+            model: warning[:model],
+            error_message: warning[:error_message],
+            suggestions: warning[:suggestions],
+            timestamp: Time.now.utc.iso8601,
+          )
+        end
+      end
+
+      warnings
+    end
+
     # Cleanup all MCP clients
     #
     # Stops all MCP client connections gracefully.

data/lib/swarm_sdk/tools/delegate.rb

@@ -18,13 +18,15 @@ module SwarmSDK
       # @param agent_name [Symbol, String] Name of the agent using this tool
       # @param swarm [Swarm] The swarm instance
       # @param hook_registry [Hooks::Registry] Registry for callbacks
+      # @param delegating_chat [Agent::Chat, nil] The chat instance of the agent doing the delegating (for accessing hooks)
       def initialize(
         delegate_name:,
         delegate_description:,
         delegate_chat:,
         agent_name:,
         swarm:,
-        hook_registry:
+        hook_registry:,
+        delegating_chat: nil
       )
         super()
 
@@ -34,6 +36,7 @@ module SwarmSDK
         @agent_name = agent_name
         @swarm = swarm
         @hook_registry = hook_registry
+        @delegating_chat = delegating_chat
 
         # Generate tool name in the expected format: DelegateTaskTo[AgentName]
         @tool_name = "DelegateTaskTo#{delegate_name.to_s.capitalize}"
@@ -60,6 +63,13 @@ module SwarmSDK
       # @param task [String] Task to delegate
       # @return [String] Result from delegate agent or error message
       def execute(task:)
+        # Get agent-specific hooks from the delegating chat instance
+        agent_hooks = if @delegating_chat&.respond_to?(:hook_agent_hooks)
+          @delegating_chat.hook_agent_hooks || {}
+        else
+          {}
+        end
+
         # Trigger pre_delegation callback
         context = Hooks::Context.new(
           event: :pre_delegation,
@@ -74,7 +84,8 @@ module SwarmSDK
         )
 
         executor = Hooks::Executor.new(@hook_registry, logger: RubyLLM.logger)
-        result = executor.execute_safe(event: :pre_delegation, context: context, callbacks: [])
+        pre_agent_hooks = agent_hooks[:pre_delegation] || []
+        result = executor.execute_safe(event: :pre_delegation, context: context, callbacks: pre_agent_hooks)
 
         # Check if callback halted or replaced the delegation
         if result.halt?
@@ -102,7 +113,8 @@ module SwarmSDK
           },
         )
 
-        post_result = executor.execute_safe(event: :post_delegation, context: post_context, callbacks: [])
+        post_agent_hooks = agent_hooks[:post_delegation] || []
+        post_result = executor.execute_safe(event: :post_delegation, context: post_context, callbacks: post_agent_hooks)
 
         # Return modified result if callback replaces it
         if post_result.replace?

data/lib/swarm_sdk/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SwarmSDK
-  VERSION = "2.0.0-2"
+  VERSION = "2.0.0"
 end