swarm_sdk 2.2.0 → 2.3.0

data/lib/swarm_sdk/builders/base_builder.rb

@@ -0,0 +1,409 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module Builders
+    # Base builder with shared DSL methods for Swarm and Workflow builders
+    #
+    # Provides common functionality:
+    # - Basic configuration (name, id, scratchpad)
+    # - Agent definition (inline DSL, markdown files, with overrides)
+    # - All agents configuration
+    # - External swarms registry
+    # - Validation helpers
+    # - Merging logic
+    #
+    # Subclasses must implement:
+    # - build_swarm - Build and return the appropriate instance
+    # - Type-specific DSL methods (lead for Swarm, node/start_node for Workflow)
+    #
+    class BaseBuilder
+      def initialize(allow_filesystem_tools: nil)
+        @swarm_id = nil
+        @swarm_name = nil
+        @agents = {}
+        @all_agents_config = nil
+        @swarm_registry_config = []
+        @scratchpad = :disabled
+        @allow_filesystem_tools = allow_filesystem_tools
+      end
+
+      # Set swarm ID
+      #
+      # @param swarm_id [String] Unique identifier for this swarm/workflow
+      def id(swarm_id)
+        @swarm_id = swarm_id
+      end
+
+      # Set swarm/workflow name
+      def name(swarm_name)
+        @swarm_name = swarm_name
+      end
+
+      # Configure scratchpad mode
+      #
+      # For Workflow: :enabled (shared across nodes), :per_node (isolated), or :disabled
+      # For Swarm: :enabled or :disabled
+      #
+      # @param mode [Symbol, Boolean] Scratchpad mode
+      def scratchpad(mode)
+        @scratchpad = mode
+      end
+
+      # Register external swarms for composable swarms
+      #
+      # @example
+      #   swarms do
+      #     register "code_review", file: "./swarms/code_review.rb"
+      #     register "testing", file: "./swarms/testing.yml", keep_context: false
+      #   end
+      #
+      # @yield Block containing register() calls
+      def swarms(&block)
+        builder = Swarm::SwarmRegistryBuilder.new
+        builder.instance_eval(&block)
+        @swarm_registry_config = builder.registrations
+      end
+
+      # Define an agent with fluent API or load from markdown content
+      #
+      # Supports two forms:
+      # 1. Inline DSL: agent :name do ... end
+      # 2. Markdown content: agent :name, <<~MD ... MD
+      #
+      # @example Inline DSL
+      #   agent :backend do
+      #     model "gpt-5"
+      #     system_prompt "You build APIs"
+      #     tools :Read, :Write
+      #   end
+      #
+      # @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 do ... end (markdown + overrides)
+        if content.is_a?(String) && block_given? && markdown_content?(content)
+          load_agent_from_markdown_with_overrides(content, name, &block)
+        # Case 2: agent :name, <<~MD (markdown only)
+        elsif content.is_a?(String) && !block_given? && markdown_content?(content)
+          load_agent_from_markdown(content, name)
+        # Case 3: 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 OR agent :name, <<~MD do ... end"
+        end
+      end
+
+      # Configure all agents with a block
+      #
+      # @example
+      #   all_agents do
+      #     tools :Read, :Write
+      #
+      #     hook :pre_tool_use, matcher: "Write" do |ctx|
+      #       # Validation for all agents
+      #     end
+      #   end
+      def all_agents(&block)
+        builder = Swarm::AllAgentsBuilder.new
+        builder.instance_eval(&block)
+        @all_agents_config = builder
+      end
+
+      # Build the actual Swarm or Workflow instance
+      #
+      # Subclasses must implement this method.
+      #
+      # @return [Swarm, Workflow] Configured instance
+      def build_swarm
+        raise NotImplementedError, "#{self.class} must implement #build_swarm"
+      end
+
+      protected
+
+      # 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)
+        definition = MarkdownParser.parse(content, name_override)
+        @agents[definition.name] = { __file_config__: definition.to_h }
+      end
+
+      # Load an agent from markdown content with DSL overrides
+      #
+      # @param content [String] Markdown content with frontmatter
+      # @param name_override [Symbol, nil] Optional name to override frontmatter name
+      # @yield Block with DSL overrides
+      # @return [void]
+      def load_agent_from_markdown_with_overrides(content, name_override = nil, &block)
+        definition = MarkdownParser.parse(content, name_override)
+
+        builder = Agent::Builder.new(definition.name)
+        apply_definition_to_builder(builder, definition.to_h)
+        builder.instance_eval(&block)
+
+        @agents[definition.name] = builder
+      end
+
+      # Apply agent definition hash to a builder
+      #
+      # @param builder [Agent::Builder] Builder to configure
+      # @param config [Hash] Configuration hash from definition
+      # @return [void]
+      def apply_definition_to_builder(builder, config)
+        builder.description(config[:description]) if config[:description]
+        builder.model(config[:model]) if config[:model]
+        builder.provider(config[:provider]) if config[:provider]
+        builder.base_url(config[:base_url]) if config[:base_url]
+        builder.api_version(config[:api_version]) if config[:api_version]
+        builder.context_window(config[:context_window]) if config[:context_window]
+        builder.system_prompt(config[:system_prompt]) if config[:system_prompt]
+        builder.directory(config[:directory]) if config[:directory]
+        builder.timeout(config[:timeout]) if config[:timeout]
+        builder.parameters(config[:parameters]) if config[:parameters]
+        builder.headers(config[:headers]) if config[:headers]
+        builder.coding_agent(config[:coding_agent]) unless config[:coding_agent].nil?
+        builder.bypass_permissions(config[:bypass_permissions]) if config[:bypass_permissions]
+        builder.disable_default_tools(config[:disable_default_tools]) unless config[:disable_default_tools].nil?
+
+        # Add tools from markdown
+        if config[:tools]&.any?
+          tool_names = config[:tools].map do |tool|
+            tool.is_a?(Hash) ? tool[:name] : tool
+          end
+          builder.tools(*tool_names)
+        end
+
+        # Add delegates_to
+        builder.delegates_to(*config[:delegates_to]) if config[:delegates_to]&.any?
+
+        # Add MCP servers
+        config[:mcp_servers]&.each do |server|
+          builder.mcp_server(server[:name], **server.except(:name))
+        end
+      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
+
+        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__]
+            merged_config = merge_all_agents_into_config(all_agents_hash, file_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(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
+      #
+      # @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
+            merged[:tools] = Array(merged[:tools]) + Array(value)
+          when :delegates_to
+            merged[:delegates_to] = Array(merged[:delegates_to]) + Array(value)
+          when :parameters
+            merged[:parameters] = (merged[:parameters] || {}).merge(value || {})
+          when :headers
+            merged[:headers] = (merged[:headers] || {}).merge(value || {})
+          else
+            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
+      #
+      # @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)
+        if all_agents_hash[:model] && !agent_builder.model_set?
+          agent_builder.model(all_agents_hash[:model])
+        end
+
+        if all_agents_hash[:provider] && !agent_builder.provider_set?
+          agent_builder.provider(all_agents_hash[:provider])
+        end
+
+        if all_agents_hash[:base_url] && !agent_builder.base_url_set?
+          agent_builder.base_url(all_agents_hash[:base_url])
+        end
+
+        if all_agents_hash[:api_version] && !agent_builder.api_version_set?
+          agent_builder.api_version(all_agents_hash[:api_version])
+        end
+
+        if all_agents_hash[:timeout] && !agent_builder.timeout_set?
+          agent_builder.timeout(all_agents_hash[:timeout])
+        end
+
+        if all_agents_hash[:parameters]
+          merged_params = all_agents_hash[:parameters].merge(agent_builder.parameters)
+          agent_builder.parameters(merged_params)
+        end
+
+        if all_agents_hash[:headers]
+          merged_headers = all_agents_hash[:headers].merge(agent_builder.headers)
+          agent_builder.headers(merged_headers)
+        end
+
+        if !all_agents_hash[:coding_agent].nil? && !agent_builder.coding_agent_set?
+          agent_builder.coding_agent(all_agents_hash[:coding_agent])
+        end
+      end
+
+      # Validate all_agents filesystem tools
+      #
+      # @raise [ConfigurationError] If filesystem tools are disabled and all_agents has them
+      # @return [void]
+      def validate_all_agents_filesystem_tools
+        resolved_setting = if @allow_filesystem_tools.nil?
+          SwarmSDK.settings.allow_filesystem_tools
+        else
+          @allow_filesystem_tools
+        end
+
+        return if resolved_setting
+        return unless @all_agents_config&.tools_list&.any?
+
+        forbidden = @all_agents_config.tools_list.select do |tool|
+          SwarmSDK::Swarm::ToolConfigurator::FILESYSTEM_TOOLS.include?(tool.to_sym)
+        end
+
+        return if forbidden.empty?
+
+        raise ConfigurationError,
+          "Filesystem tools are globally disabled (SwarmSDK.settings.allow_filesystem_tools = false) " \
+            "but all_agents configuration includes: #{forbidden.join(", ")}.\n\n" \
+            "This is a system-wide security setting that cannot be overridden by swarm configuration.\n" \
+            "To use filesystem tools, set SwarmSDK.settings.allow_filesystem_tools = true before loading the swarm."
+      end
+
+      # Validate individual agent filesystem tools
+      #
+      # @raise [ConfigurationError] If filesystem tools are disabled and any agent has them
+      # @return [void]
+      def validate_agent_filesystem_tools
+        resolved_setting = if @allow_filesystem_tools.nil?
+          SwarmSDK.settings.allow_filesystem_tools
+        else
+          @allow_filesystem_tools
+        end
+
+        return if resolved_setting
+
+        @agents.each do |agent_name, agent_builder_or_config|
+          tools_list = if agent_builder_or_config.is_a?(Hash) && agent_builder_or_config.key?(:__file_config__)
+            agent_builder_or_config[:__file_config__][:tools] || []
+          elsif agent_builder_or_config.is_a?(Agent::Builder)
+            agent_builder_or_config.tools_list
+          else
+            []
+          end
+
+          tool_names = tools_list.map do |tool|
+            name = tool.is_a?(Hash) ? tool[:name] : tool
+            name.to_sym
+          end
+
+          forbidden = tool_names.select do |tool|
+            SwarmSDK::Swarm::ToolConfigurator::FILESYSTEM_TOOLS.include?(tool)
+          end
+
+          next if forbidden.empty?
+
+          raise ConfigurationError,
+            "Filesystem tools are globally disabled (SwarmSDK.settings.allow_filesystem_tools = false) " \
+              "but agent '#{agent_name}' attempts to use: #{forbidden.join(", ")}.\n\n" \
+              "This is a system-wide security setting that cannot be overridden by swarm configuration.\n" \
+              "To use filesystem tools, set SwarmSDK.settings.allow_filesystem_tools = true before loading the swarm."
+        end
+      end
+
+      # Build agent definitions from builders or file configs
+      #
+      # Handles both Agent::Builder (inline DSL) and file configs (from files).
+      # Merges all_agents config before building.
+      #
+      # @return [Hash<Symbol, Agent::Definition>] Agent definitions
+      def build_agent_definitions
+        # Merge all_agents config first
+        merge_all_agents_config_into_agents if @all_agents_config
+
+        # Build definitions
+        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
+
+        agent_definitions
+      end
+    end
+  end
+end

data/lib/swarm_sdk/concerns/cleanupable.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module Concerns
+    # Shared cleanup functionality for Swarm and Workflow
+    #
+    # Both classes must have:
+    # - mcp_clients: Hash of MCP client arrays
+    # - delegation_instances_hash: Hash of delegation instances (via Snapshotable)
+    #
+    module Cleanupable
+      # Cleanup all MCP clients
+      #
+      # Stops all MCP client connections gracefully.
+      # Should be called when the swarm/workflow is no longer needed.
+      #
+      # @return [void]
+      def cleanup
+        # Check if there's anything to clean up
+        return if @mcp_clients.empty? && (!delegation_instances_hash || delegation_instances_hash.empty?)
+
+        # Stop MCP clients for all agents
+        @mcp_clients.each do |agent_name, clients|
+          clients.each do |client|
+            client.stop
+            RubyLLM.logger.debug("SwarmSDK: Stopped MCP client '#{client.name}' for agent #{agent_name}")
+          rescue StandardError => e
+            RubyLLM.logger.debug("SwarmSDK: Error stopping MCP client '#{client.name}': #{e.message}")
+          end
+        end
+
+        @mcp_clients.clear
+
+        # Clear delegation instances
+        delegation_instances_hash&.clear
+      end
+    end
+  end
+end

data/lib/swarm_sdk/concerns/snapshotable.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module Concerns
+    # Shared snapshot and restore functionality for Swarm and Workflow
+    #
+    # Both classes must implement:
+    # - primary_agents: Returns hash of primary agent instances
+    # - delegation_instances_hash: Returns hash of delegation instances
+    # - agent_definitions: Returns hash of agent definitions
+    # - swarm_id: Returns the swarm/workflow ID
+    # - parent_swarm_id: Returns the parent ID (or nil)
+    # - name: Returns the swarm/workflow name
+    #
+    module Snapshotable
+      # Create snapshot of current conversation state
+      #
+      # Returns a Snapshot object containing:
+      # - All agent conversations (@messages arrays)
+      # - Agent context state (warnings, compression, TodoWrite tracking, skills)
+      # - Delegation instance conversations
+      # - Scratchpad contents (volatile shared storage)
+      # - Read tracking state (which files each agent has read with digests)
+      # - Memory read tracking state (which memory entries each agent has read with digests)
+      #
+      # @return [Snapshot] Snapshot object with convenient serialization methods
+      def snapshot
+        StateSnapshot.new(self).snapshot
+      end
+
+      # Restore conversation state from snapshot
+      #
+      # Accepts a Snapshot object, hash, or JSON string. Validates compatibility
+      # between snapshot and current configuration, restores agent conversations,
+      # context state, scratchpad, and read tracking.
+      #
+      # The swarm/workflow must be created with the SAME configuration (agent definitions,
+      # tools, prompts) as when the snapshot was created. Only conversation state
+      # is restored from the snapshot.
+      #
+      # @param snapshot [Snapshot, Hash, String] Snapshot object, hash, or JSON string
+      # @param preserve_system_prompts [Boolean] Use historical system prompts instead of current config (default: false)
+      # @return [RestoreResult] Result with warnings about skipped agents
+      def restore(snapshot, preserve_system_prompts: false)
+        StateRestorer.new(self, snapshot, preserve_system_prompts: preserve_system_prompts).restore
+      end
+
+      # Interface method: Get primary agent instances
+      #
+      # Must be implemented by including class.
+      #
+      # @return [Hash<Symbol, Agent::Chat>] Primary agent instances
+      def primary_agents
+        raise NotImplementedError, "#{self.class} must implement #primary_agents"
+      end
+
+      # Interface method: Get delegation instance hash
+      #
+      # Must be implemented by including class.
+      #
+      # @return [Hash<String, Agent::Chat>] Delegation instances with keys like "delegate@delegator"
+      def delegation_instances_hash
+        raise NotImplementedError, "#{self.class} must implement #delegation_instances_hash"
+      end
+    end
+  end
+end

data/lib/swarm_sdk/concerns/validatable.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module Concerns
+    # Shared validation functionality for Swarm and Workflow
+    #
+    # Both classes must have:
+    # - agent_definitions: Hash of Agent::Definition objects
+    # - swarm_id: Swarm/workflow identifier
+    # - parent_swarm_id: Parent identifier (or nil)
+    #
+    module Validatable
+      # Validate swarm/workflow 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
+      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
+      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],
+              swarm_id: @swarm_id,
+              parent_swarm_id: @parent_swarm_id,
+              model: warning[:model],
+              error_message: warning[:error_message],
+              suggestions: warning[:suggestions],
+              timestamp: Time.now.utc.iso8601,
+            )
+          end
+        end
+
+        warnings
+      end
+    end
+  end
+end