swarm_memory 2.1.2 → 2.1.4

data/lib/swarm_sdk/agent/system_prompt_builder.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module Agent
+    # Builds system prompts for agents
+    #
+    # This class encapsulates all system prompt construction logic, including:
+    # - Base system prompt rendering (for coding agents)
+    # - Non-coding base prompt rendering
+    # - Plugin prompt contribution collection
+    # - Combining base and custom prompts
+    #
+    # ## Safety Note for SwarmMemory Integration
+    #
+    # This is an INTERNAL helper that receives Definition attributes as input.
+    # Definition remains the single source of truth with all instance variables.
+    # SwarmMemory uses `agent_definition.instance_eval { binding }` for ERB templating,
+    # which requires all properties to be on Definition object. This helper is safe
+    # because it doesn't affect Definition's structure - it only extracts logic.
+    class SystemPromptBuilder
+      BASE_SYSTEM_PROMPT_PATH = File.expand_path("../prompts/base_system_prompt.md.erb", __dir__)
+
+      class << self
+        # Build the complete system prompt for an agent
+        #
+        # @param custom_prompt [String, nil] Custom system prompt from configuration
+        # @param coding_agent [Boolean] Whether agent is configured for coding tasks
+        # @param disable_default_tools [Boolean, Array, nil] Default tools disable configuration
+        # @param directory [String] Agent's working directory
+        # @param definition [Definition] Full definition for plugin contributions
+        # @return [String] Complete system prompt
+        def build(custom_prompt:, coding_agent:, disable_default_tools:, directory:, definition:)
+          new(
+            custom_prompt: custom_prompt,
+            coding_agent: coding_agent,
+            disable_default_tools: disable_default_tools,
+            directory: directory,
+            definition: definition,
+          ).build
+        end
+      end
+
+      def initialize(custom_prompt:, coding_agent:, disable_default_tools:, directory:, definition:)
+        @custom_prompt = custom_prompt
+        @coding_agent = coding_agent
+        @disable_default_tools = disable_default_tools
+        @directory = directory
+        @definition = definition
+      end
+
+      def build
+        prompt = base_prompt_section
+        prompt = append_plugin_contributions(prompt)
+        prompt
+      end
+
+      private
+
+      def base_prompt_section
+        if @coding_agent
+          build_coding_agent_prompt
+        elsif default_tools_enabled?
+          build_non_coding_agent_prompt
+        else
+          (@custom_prompt || "").to_s
+        end
+      end
+
+      def build_coding_agent_prompt
+        rendered_base = render_base_system_prompt
+
+        if @custom_prompt && !@custom_prompt.strip.empty?
+          "#{rendered_base}\n\n#{@custom_prompt}"
+        else
+          rendered_base
+        end
+      end
+
+      def build_non_coding_agent_prompt
+        non_coding_base = render_non_coding_base_prompt
+
+        if @custom_prompt && !@custom_prompt.strip.empty?
+          "#{non_coding_base}\n\n#{@custom_prompt}"
+        else
+          non_coding_base
+        end
+      end
+
+      def default_tools_enabled?
+        @disable_default_tools != true
+      end
+
+      def render_base_system_prompt
+        cwd = @directory || Dir.pwd
+        platform = RUBY_PLATFORM
+        os_version = begin
+          %x(uname -sr 2>/dev/null).strip
+        rescue
+          RUBY_PLATFORM
+        end
+        date = Time.now.strftime("%Y-%m-%d")
+
+        template_content = File.read(BASE_SYSTEM_PROMPT_PATH)
+        ERB.new(template_content).result(binding)
+      end
+
+      def render_non_coding_base_prompt
+        cwd = @directory || Dir.pwd
+        platform = RUBY_PLATFORM
+        os_version = begin
+          %x(uname -sr 2>/dev/null).strip
+        rescue
+          RUBY_PLATFORM
+        end
+        date = Time.now.strftime("%Y-%m-%d")
+
+        <<~PROMPT.strip
+          # Today's date
+
+          <today-date>
+          #{date}
+          #</today-date>
+
+          # Current Environment
+
+          <env>
+          Working directory: #{cwd}
+          Platform: #{platform}
+          OS Version: #{os_version}
+          </env>
+        PROMPT
+      end
+
+      def append_plugin_contributions(prompt)
+        contributions = collect_plugin_prompt_contributions
+        return prompt if contributions.empty?
+
+        combined_contributions = contributions.join("\n\n")
+
+        if prompt && !prompt.strip.empty?
+          "#{prompt}\n\n#{combined_contributions}"
+        else
+          combined_contributions
+        end
+      end
+
+      def collect_plugin_prompt_contributions
+        contributions = []
+
+        PluginRegistry.all.each do |plugin|
+          next unless plugin.storage_enabled?(@definition)
+
+          contribution = plugin.system_prompt_contribution(agent_definition: @definition, storage: nil)
+          contributions << contribution if contribution && !contribution.strip.empty?
+        end
+
+        contributions
+      end
+    end
+  end
+end

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