claude_swarm 1.0.9 → 1.0.11

data/lib/swarm_sdk/agent/context.rb

@@ -30,8 +30,7 @@ module SwarmSDK
       # 60% triggers automatic compression, 80%/90% are informational warnings
       CONTEXT_WARNING_THRESHOLDS = [60, 80, 90].freeze
 
-      # Threshold at which automatic compression is triggered
-      COMPRESSION_THRESHOLD = 60
+      # NOTE: Compression threshold now accessed via SwarmSDK.config.context_compression_threshold
 
       attr_reader :name, :delegation_tools, :metadata, :warning_thresholds_hit, :swarm_id, :parent_swarm_id
 

data/lib/swarm_sdk/agent/definition.rb

@@ -18,11 +18,6 @@ module SwarmSDK
     #     system_prompt: "You build APIs"
     #   })
     class Definition
-      DEFAULT_MODEL = "gpt-5"
-      DEFAULT_PROVIDER = "openai"
-      DEFAULT_TIMEOUT = 300 # 5 minutes - reasoning models can take a while
-      BASE_SYSTEM_PROMPT_PATH = File.expand_path("../prompts/base_system_prompt.md.erb", __dir__)
-
       attr_reader :name,
         :description,
         :model,
@@ -44,7 +39,7 @@ module SwarmSDK
         :agent_permissions,
         :assume_model_exists,
         :hooks,
-        :memory,
+        :plugin_configs,
         :shared_across_delegations
 
       attr_accessor :bypass_permissions, :max_concurrent_tools
@@ -72,14 +67,14 @@ module SwarmSDK
         end
 
         @description = config[:description]
-        @model = config[:model] || DEFAULT_MODEL
-        @provider = config[:provider] || DEFAULT_PROVIDER
+        @model = config[:model] || SwarmSDK.config.default_model
+        @provider = config[:provider] || SwarmSDK.config.default_provider
         @base_url = config[:base_url]
         @api_version = config[:api_version]
         @context_window = config[:context_window] # Explicit context window override
         @parameters = config[:parameters] || {}
         @headers = Utils.stringify_keys(config[:headers] || {})
-        @timeout = config[:timeout] || DEFAULT_TIMEOUT
+        @timeout = config[:timeout] || SwarmSDK.config.agent_request_timeout
         @bypass_permissions = config[:bypass_permissions] || false
         @max_concurrent_tools = config[:max_concurrent_tools]
         # Always assume model exists - SwarmSDK validates models separately using models.json
@@ -100,9 +95,9 @@ module SwarmSDK
         # Parse directory first so it can be used in system prompt rendering
         @directory = parse_directory(config[:directory])
 
-        # Parse memory configuration BEFORE building system prompt
-        # (memory prompt needs to be appended if memory is enabled)
-        @memory = parse_memory_config(config[:memory])
+        # Extract plugin configurations (generic bucket for all plugin-specific keys)
+        # This allows plugins to store their config without SDK knowing about them
+        @plugin_configs = extract_plugin_configs(config)
 
         # Delegation isolation mode (default: false = isolated instances per delegation)
         @shared_across_delegations = config[:shared_across_delegations] || false
@@ -132,40 +127,20 @@ module SwarmSDK
         validate!
       end
 
-      # Check if memory is enabled for this agent
+      # Get plugin-specific configuration
       #
-      # @return [Boolean]
-      def memory_enabled?
-        return false if @memory.nil?
-
-        # MemoryConfig object (from DSL)
-        return @memory.enabled? if @memory.respond_to?(:enabled?)
-
-        # Hash (from YAML) - check for directory key
-        if @memory.is_a?(Hash)
-          directory = @memory[:directory] || @memory["directory"]
-          return !directory.nil? && !directory.to_s.strip.empty?
-        end
-
-        false
-      end
-
-      # Parse memory configuration from Hash or MemoryConfig object
+      # Plugins store their configuration in the generic plugin_configs hash.
+      # This allows SDK to remain plugin-agnostic while plugins can store
+      # arbitrary configuration.
+      #
+      # @param plugin_name [Symbol] Plugin name (e.g., :memory)
+      # @return [Object, nil] Plugin configuration or nil if not present
       #
-      # @param memory_config [Hash, Object, nil] Memory configuration
-      # @return [Object, Hash, nil] Memory config (could be MemoryConfig from swarm_memory or Hash)
-      def parse_memory_config(memory_config)
-        return if memory_config.nil?
-
-        # If it's a MemoryConfig object (duck typing - has directory, adapter, mode methods)
-        # return as-is. This could be SwarmMemory::DSL::MemoryConfig or any compatible object.
-        return memory_config if memory_config.respond_to?(:directory) &&
-          memory_config.respond_to?(:adapter) &&
-          memory_config.respond_to?(:enabled?)
-
-        # If it's a hash (from YAML), keep it as a hash
-        # Plugin will create storage adapter based on the hash values
-        memory_config
+      # @example
+      #   agent_definition.plugin_config(:memory)
+      #   # => { directory: "tmp/memory", mode: :researcher }
+      def plugin_config(plugin_name)
+        @plugin_configs[plugin_name.to_sym] || @plugin_configs[plugin_name.to_s]
       end
 
       def to_h
@@ -285,122 +260,59 @@ module SwarmSDK
       end
 
       def build_full_system_prompt(custom_prompt)
-        # Build the base prompt based on coding_agent setting
-        prompt = if @coding_agent
-          # Coding agent: include full base prompt
-          rendered_base = render_base_system_prompt
-
-          if custom_prompt && !custom_prompt.strip.empty?
-            "#{rendered_base}\n\n#{custom_prompt}"
-          else
-            rendered_base
-          end
-        elsif default_tools_enabled?
-          # Non-coding agent: optionally include TODO/Scratchpad sections if default tools available
-          non_coding_base = render_non_coding_base_prompt
-
-          if custom_prompt && !custom_prompt.strip.empty?
-            # Prepend TODO/Scratchpad info before custom prompt
-            "#{non_coding_base}\n\n#{custom_prompt}"
-          else
-            # No custom prompt: just return TODO/Scratchpad info
-            non_coding_base
-          end
-        else
-          # No default tools: return only custom prompt
-          (custom_prompt || "").to_s
-        end
-
-        # Append plugin contributions to system prompt
-        plugin_contributions = collect_plugin_prompt_contributions
-        if plugin_contributions.any?
-          combined_contributions = plugin_contributions.join("\n\n")
-          prompt = if prompt && !prompt.strip.empty?
-            "#{prompt}\n\n#{combined_contributions}"
-          else
-            combined_contributions
-          end
-        end
-
-        prompt
-      end
-
-      # Check if default tools are enabled (i.e., not disabled)
-      #
-      # @return [Boolean] True if default tools should be included
-      def default_tools_enabled?
-        @disable_default_tools != true
+        # Delegate to SystemPromptBuilder for all prompt construction logic
+        # This keeps Definition focused on data storage while extracting complex logic
+        SystemPromptBuilder.build(
+          custom_prompt: custom_prompt,
+          coding_agent: @coding_agent,
+          disable_default_tools: @disable_default_tools,
+          directory: @directory,
+          definition: self,
+        )
       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)
+      def parse_directory(directory_config)
+        directory_config ||= "."
+        File.expand_path(directory_config.to_s)
       end
 
-      # Collect system prompt contributions from all plugins
+      # Extract plugin-specific configuration keys from the config hash
       #
-      # Asks each registered plugin if it wants to contribute to the system prompt.
-      # Plugins can return custom instructions based on their configuration.
+      # Standard SDK keys are filtered out, leaving only plugin-specific keys.
+      # This allows plugins to add their own configuration without SDK modifications.
       #
-      # @return [Array<String>] Array of prompt contributions from plugins
-      def collect_plugin_prompt_contributions
-        contributions = []
-
-        PluginRegistry.all.each do |plugin|
-          # Check if plugin has storage enabled for this agent
-          next unless plugin.storage_enabled?(self)
-
-          # Ask plugin for prompt contribution
-          # Note: storage is not available yet at this point, so we pass nil
-          contribution = plugin.system_prompt_contribution(agent_definition: self, storage: nil)
-          contributions << contribution if contribution && !contribution.strip.empty?
-        end
-
-        contributions
-      end
-
-      def render_non_coding_base_prompt
-        # Simplified base prompt for non-coding agents
-        # Includes environment info only
-        # Does not steer towards coding tasks
-        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 parse_directory(directory_config)
-        directory_config ||= "."
-        File.expand_path(directory_config.to_s)
+      # @param config [Hash] Full agent configuration
+      # @return [Hash] Plugin-specific configuration (keys not recognized by SDK)
+      def extract_plugin_configs(config)
+        standard_keys = [
+          :name,
+          :description,
+          :model,
+          :provider,
+          :base_url,
+          :api_version,
+          :context_window,
+          :parameters,
+          :headers,
+          :timeout,
+          :bypass_permissions,
+          :max_concurrent_tools,
+          :assume_model_exists,
+          :disable_default_tools,
+          :coding_agent,
+          :directory,
+          :system_prompt,
+          :tools,
+          :delegates_to,
+          :mcp_servers,
+          :hooks,
+          :default_permissions,
+          :permissions,
+          :shared_across_delegations,
+          :directories,
+        ]
+
+        config.reject { |k, _| standard_keys.include?(k.to_sym) }
       end
 
       # Parse tools configuration with permissions support

data/lib/swarm_sdk/agent/llm_instrumentation_middleware.rb

@@ -64,7 +64,8 @@ module SwarmSDK
         @on_request.call(request_data)
       rescue StandardError => e
         # Don't let logging errors break the request
-        RubyLLM.logger.error("LLM instrumentation request error: #{e.message}")
+        LogStream.emit_error(e, source: "llm_instrumentation_middleware", context: "emit_request_event", provider: @provider_name)
+        RubyLLM.logger.debug("LLM instrumentation request error: #{e.message}")
       end
 
       # Emit response event
@@ -97,7 +98,8 @@ module SwarmSDK
         @on_response.call(response_data)
       rescue StandardError => e
         # Don't let logging errors break the response
-        RubyLLM.logger.error("LLM instrumentation response error: #{e.message}")
+        LogStream.emit_error(e, source: "llm_instrumentation_middleware", context: "emit_response_event", provider: @provider_name)
+        RubyLLM.logger.debug("LLM instrumentation response error: #{e.message}")
       end
 
       # Sanitize headers by removing sensitive data

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.memory_configured?(@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/agent_registry.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  # Global registry for reusable agent definitions
+  #
+  # AgentRegistry allows declaring agents in separate files that can be
+  # referenced by name in swarm definitions. This promotes code reuse and
+  # separation of concerns - agent definitions can live in dedicated files
+  # while swarm configurations compose them together.
+  #
+  # ## Usage
+  #
+  # Register agents globally (typically in separate files):
+  #
+  #   # agents/backend.rb
+  #   SwarmSDK.agent :backend do
+  #     model "claude-sonnet-4"
+  #     description "Backend API developer"
+  #     system_prompt "You build REST APIs"
+  #     tools :Read, :Edit, :Bash
+  #   end
+  #
+  # Reference registered agents in swarm definitions:
+  #
+  #   # swarm.rb
+  #   SwarmSDK.build do
+  #     name "Dev Team"
+  #     lead :backend
+  #
+  #     agent :backend  # Pulls from registry
+  #   end
+  #
+  # ## Override Support
+  #
+  # Registered agents can be extended with additional configuration:
+  #
+  #   SwarmSDK.build do
+  #     name "Dev Team"
+  #     lead :backend
+  #
+  #     agent :backend do
+  #       # Registry config is applied first, then this block
+  #       tools :CustomTool  # Adds to tools from registry
+  #       delegates_to :database
+  #     end
+  #   end
+  #
+  # @note This registry is not thread-safe. In multi-threaded environments,
+  #   register all agents before spawning threads, or synchronize access
+  #   externally. For typical fiber-based async usage (the default in SwarmSDK),
+  #   this is not a concern.
+  #
+  class AgentRegistry
+    @agents = {}
+
+    class << self
+      # Register an agent definition block
+      #
+      # Stores a configuration block that will be executed when the agent
+      # is referenced in a swarm definition. The block receives an
+      # Agent::Builder context and can use all builder DSL methods.
+      #
+      # @param name [Symbol, String] Agent name (will be symbolized)
+      # @yield Agent configuration block using Agent::Builder DSL
+      # @return [void]
+      # @raise [ArgumentError] If no block is provided
+      # @raise [ArgumentError] If agent with same name is already registered
+      #
+      # @example Register a backend agent
+      #   SwarmSDK::AgentRegistry.register(:backend) do
+      #     model "claude-sonnet-4"
+      #     description "Backend developer"
+      #     tools :Read, :Edit, :Bash
+      #   end
+      #
+      # @example Register with MCP servers
+      #   SwarmSDK::AgentRegistry.register(:filesystem_agent) do
+      #     model "gpt-4"
+      #     description "File manager"
+      #     mcp_server :fs, type: :stdio, command: "npx", args: ["-y", "@modelcontextprotocol/server-filesystem"]
+      #   end
+      def register(name, &block)
+        raise ArgumentError, "Block required for agent registration" unless block_given?
+
+        sym_name = name.to_sym
+        if @agents.key?(sym_name)
+          raise ArgumentError,
+            "Agent '#{sym_name}' is already registered. " \
+              "Use SwarmSDK.clear_agent_registry! to reset, or choose a different name."
+        end
+
+        @agents[sym_name] = block
+      end
+
+      # Retrieve a registered agent block
+      #
+      # @param name [Symbol, String] Agent name
+      # @return [Proc, nil] The registration block or nil if not found
+      #
+      # @example
+      #   block = SwarmSDK::AgentRegistry.get(:backend)
+      #   builder.instance_eval(&block) if block
+      def get(name)
+        @agents[name.to_sym]
+      end
+
+      # Check if an agent is registered
+      #
+      # @param name [Symbol, String] Agent name
+      # @return [Boolean] true if agent is registered
+      #
+      # @example
+      #   if SwarmSDK::AgentRegistry.registered?(:backend)
+      #     puts "Backend agent is available"
+      #   end
+      def registered?(name)
+        @agents.key?(name.to_sym)
+      end
+
+      # List all registered agent names
+      #
+      # @return [Array<Symbol>] Names of all registered agents
+      #
+      # @example
+      #   SwarmSDK::AgentRegistry.names
+      #   # => [:backend, :frontend, :database]
+      def names
+        @agents.keys
+      end
+
+      # Clear all registrations
+      #
+      # Primarily useful for testing to ensure clean state between tests.
+      #
+      # @return [void]
+      #
+      # @example In test setup/teardown
+      #   def teardown
+      #     SwarmSDK::AgentRegistry.clear
+      #   end
+      def clear
+        @agents.clear
+      end
+    end
+  end
+end