claude_swarm 1.0.10 → 1.0.11

data/lib/swarm_sdk/workflow/builder.rb

@@ -119,6 +119,9 @@ module SwarmSDK
       #
       # @return [Workflow] Configured workflow instance
       def build_workflow
+        # Resolve any missing agents from global registry before building definitions
+        resolve_missing_agents_from_registry
+
         # Build agent definitions
         agent_definitions = build_agent_definitions
 
@@ -138,6 +141,52 @@ module SwarmSDK
 
         workflow
       end
+
+      # Resolve agents referenced in nodes that aren't defined at workflow level
+      #
+      # For each agent referenced in a node but not defined with `agent :name do ... end`,
+      # checks the global AgentRegistry and loads the agent if found.
+      #
+      # This allows workflows to reference globally registered agents without
+      # explicitly re-declaring them at the workflow level.
+      #
+      # @return [void]
+      # @raise [ConfigurationError] If agent not found in workflow or registry
+      def resolve_missing_agents_from_registry
+        # Collect all agents referenced in nodes
+        referenced_agents = collect_referenced_agents
+
+        # Find agents that aren't defined at workflow level
+        defined_agents = @agents.keys
+        missing_agents = referenced_agents - defined_agents
+
+        # Try to resolve each missing agent from the global registry
+        missing_agents.each do |agent_name|
+          if AgentRegistry.registered?(agent_name)
+            # Load from registry (uses same method as BaseBuilder)
+            load_agent_from_registry(agent_name)
+          else
+            raise ConfigurationError,
+              "Agent '#{agent_name}' referenced in node but not found. " \
+                "Either define at workflow level with `agent :#{agent_name} do ... end` " \
+                "or register globally with `SwarmSDK.agent :#{agent_name} do ... end`"
+          end
+        end
+      end
+
+      # Collect all agent names referenced across all nodes
+      #
+      # Includes both directly referenced agents and delegation targets.
+      #
+      # @return [Array<Symbol>] Unique agent names referenced in nodes
+      def collect_referenced_agents
+        @nodes.values.flat_map do |node_builder|
+          # Collect both direct agents and their delegation targets
+          node_builder.agent_configs.flat_map do |config|
+            [config[:agent]] + Array(config[:delegates_to])
+          end
+        end.uniq
+      end
     end
   end
 end

data/lib/swarm_sdk/workflow/node_builder.rb

@@ -214,7 +214,8 @@ module SwarmSDK
       #
       # @example
       #   input_command("scripts/validate.sh", timeout: 30)
-      def input_command(command, timeout: TransformerExecutor::DEFAULT_TIMEOUT)
+      def input_command(command, timeout: nil)
+        timeout ||= SwarmSDK.config.transformer_command_timeout
         @input_transformer_command = { command: command, timeout: timeout }
       end
 
@@ -288,7 +289,8 @@ module SwarmSDK
       #
       # @example
       #   output_command("scripts/format.sh", timeout: 30)
-      def output_command(command, timeout: TransformerExecutor::DEFAULT_TIMEOUT)
+      def output_command(command, timeout: nil)
+        timeout ||= SwarmSDK.config.transformer_command_timeout
         @output_transformer_command = { command: command, timeout: timeout }
       end
 

data/lib/swarm_sdk/workflow/transformer_executor.rb

@@ -90,8 +90,7 @@ module SwarmSDK
     #   echo "$CONTENT"
     #   exit 0
     class TransformerExecutor
-      # Backward compatibility alias - use Defaults module for new code
-      DEFAULT_TIMEOUT = Defaults::Timeouts::TRANSFORMER_COMMAND_SECONDS
+      # NOTE: Timeout now accessed via SwarmSDK.config.transformer_command_timeout
 
       # Result object for transformer execution
       TransformerResult = Struct.new(:success, :content, :skip_execution, :halt, :error_message, keyword_init: true) do
@@ -114,7 +113,9 @@ module SwarmSDK
         # @param fallback_content [String] Content to use if skip (exit 1)
         # @param timeout [Integer] Timeout in seconds (default: 60)
         # @return [TransformerResult] Result with transformed content or skip/halt flags
-        def execute(command:, context:, event:, node_name:, fallback_content:, timeout: DEFAULT_TIMEOUT)
+        def execute(command:, context:, event:, node_name:, fallback_content:, timeout: nil)
+          timeout ||= SwarmSDK.config.transformer_command_timeout
+
           # Build JSON input for transformer
           input_json = build_transformer_input(context, event, node_name)
 

data/lib/swarm_sdk.rb

@@ -63,8 +63,247 @@ module SwarmSDK
   class StateError < Error; end
 
   class << self
-    # Settings for SwarmSDK (global configuration)
-    attr_accessor :settings
+    # Get the global configuration instance
+    #
+    # @return [Config] The singleton Config instance
+    def config
+      Config.instance
+    end
+
+    # Configure SwarmSDK global settings
+    #
+    # @yield [Config] The configuration instance
+    # @return [Config] The configuration instance
+    #
+    # @example
+    #   SwarmSDK.configure do |config|
+    #     config.openai_api_key = "sk-..."
+    #     config.default_model = "claude-sonnet-4"
+    #   end
+    def configure
+      yield(config) if block_given?
+      config
+    end
+
+    # Reset configuration to defaults
+    #
+    # Clears all configuration including explicit values and cached ENV values.
+    # Use in tests to ensure clean state.
+    #
+    # @return [void]
+    def reset_config!
+      Config.reset!
+    end
+
+    # Register a global agent definition
+    #
+    # Declares an agent configuration that can be referenced by name in any
+    # swarm definition. This allows defining agents in separate files and
+    # composing them into swarms without duplication.
+    #
+    # The registered block uses the Agent::Builder DSL and is executed when
+    # the agent is referenced in a swarm definition.
+    #
+    # @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
+    #
+    # @example Register agent in separate file
+    #   # 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
+    #     delegates_to :database
+    #   end
+    #
+    # @example Reference in swarm definition
+    #   # swarm.rb
+    #   require_relative "agents/backend"
+    #
+    #   SwarmSDK.build do
+    #     name "Dev Team"
+    #     lead :backend
+    #
+    #     agent :backend  # Pulls from registry
+    #   end
+    #
+    # @example Extend registered agent with overrides
+    #   SwarmSDK.build do
+    #     name "Extended Team"
+    #     lead :backend
+    #
+    #     agent :backend do
+    #       # Registry config applied first, then this block
+    #       tools :CustomTool    # Adds to existing tools
+    #       delegates_to :cache  # Adds delegation target
+    #     end
+    #   end
+    #
+    # @see AgentRegistry
+    def agent(name, &block)
+      AgentRegistry.register(name, &block)
+    end
+
+    # Clear the global agent registry
+    #
+    # Removes all registered agent definitions. Primarily useful for testing
+    # to ensure clean state between tests.
+    #
+    # @return [void]
+    #
+    # @example In test teardown
+    #   def teardown
+    #     SwarmSDK.clear_agent_registry!
+    #   end
+    def clear_agent_registry!
+      AgentRegistry.clear
+    end
+
+    # Register a custom tool for use in swarms
+    #
+    # Provides a simple way to add tools without creating a full plugin.
+    # Tools can be registered with an explicit name or the name can be
+    # inferred from the class name.
+    #
+    # Custom tools are available to any agent that includes them in their
+    # tools configuration, just like built-in tools.
+    #
+    # @overload register_tool(tool_class)
+    #   Register a tool with name inferred from class name
+    #   @param tool_class [Class] Tool class (must inherit from RubyLLM::Tool)
+    #   @return [Symbol] The registered tool name
+    #
+    # @overload register_tool(name, tool_class)
+    #   Register a tool with explicit name
+    #   @param name [Symbol, String] Tool name
+    #   @param tool_class [Class] Tool class (must inherit from RubyLLM::Tool)
+    #   @return [Symbol] The registered tool name
+    #
+    # @raise [ArgumentError] If tool_class doesn't inherit from RubyLLM::Tool
+    # @raise [ArgumentError] If a tool with the same name is already registered
+    # @raise [ArgumentError] If the name conflicts with a built-in or plugin tool
+    #
+    # @example Register with inferred name
+    #   class WeatherTool < RubyLLM::Tool
+    #     description "Get weather for a city"
+    #     param :city, type: "string", required: true
+    #
+    #     def execute(city:)
+    #       "Weather in #{city}: Sunny, 72°F"
+    #     end
+    #   end
+    #
+    #   SwarmSDK.register_tool(WeatherTool)  # Registers as :Weather
+    #
+    # @example Register with explicit name
+    #   SwarmSDK.register_tool(:GetWeather, WeatherTool)
+    #
+    # @example Tool with agent context
+    #   class ContextAwareTool < RubyLLM::Tool
+    #     # Declare what context the tool needs
+    #     def self.creation_requirements
+    #       [:agent_name, :directory]
+    #     end
+    #
+    #     def initialize(agent_name:, directory:)
+    #       super()
+    #       @agent_name = agent_name
+    #       @directory = directory
+    #     end
+    #
+    #     description "Shows agent context"
+    #     def execute
+    #       "Agent: #{@agent_name} in #{@directory}"
+    #     end
+    #   end
+    #
+    #   SwarmSDK.register_tool(ContextAwareTool)
+    #
+    # @example Use registered tool in a swarm
+    #   SwarmSDK.register_tool(WeatherTool)
+    #
+    #   swarm = SwarmSDK.build do
+    #     name "Weather Assistant"
+    #     lead :assistant
+    #
+    #     agent :assistant do
+    #       model "claude-sonnet-4"
+    #       description "Weather helper"
+    #       tools :Weather, :Read  # Custom + built-in tools
+    #     end
+    #   end
+    #
+    # @see CustomToolRegistry For the underlying registry
+    # @see Plugin For complex tool systems requiring storage or lifecycle hooks
+    def register_tool(name_or_class, tool_class = nil)
+      if tool_class.nil?
+        # Single argument: infer name from class
+        tool_class = name_or_class
+        name = CustomToolRegistry.infer_name(tool_class)
+      else
+        # Two arguments: explicit name
+        name = name_or_class.to_sym
+      end
+
+      CustomToolRegistry.register(name, tool_class)
+      name
+    end
+
+    # Check if a custom tool is registered
+    #
+    # @param name [Symbol, String] Tool name
+    # @return [Boolean] true if the tool is registered
+    #
+    # @example
+    #   SwarmSDK.register_tool(WeatherTool)
+    #   SwarmSDK.custom_tool_registered?(:Weather)  #=> true
+    #   SwarmSDK.custom_tool_registered?(:Unknown)  #=> false
+    def custom_tool_registered?(name)
+      CustomToolRegistry.registered?(name)
+    end
+
+    # Get all registered custom tool names
+    #
+    # @return [Array<Symbol>] List of registered custom tool names
+    #
+    # @example
+    #   SwarmSDK.register_tool(WeatherTool)
+    #   SwarmSDK.register_tool(StockTool)
+    #   SwarmSDK.custom_tools  #=> [:Weather, :Stock]
+    def custom_tools
+      CustomToolRegistry.tool_names
+    end
+
+    # Unregister a custom tool
+    #
+    # @param name [Symbol, String] Tool name to unregister
+    # @return [Class, nil] The unregistered tool class, or nil if not found
+    #
+    # @example
+    #   SwarmSDK.register_tool(WeatherTool)
+    #   SwarmSDK.unregister_tool(:Weather)
+    #   SwarmSDK.custom_tool_registered?(:Weather)  #=> false
+    def unregister_tool(name)
+      CustomToolRegistry.unregister(name)
+    end
+
+    # Clear all registered custom tools
+    #
+    # Removes all custom tool registrations. Primarily useful for testing
+    # to ensure clean state between tests.
+    #
+    # @return [void]
+    #
+    # @example In test teardown
+    #   def teardown
+    #     SwarmSDK.clear_custom_tools!
+    #   end
+    def clear_custom_tools!
+      CustomToolRegistry.clear
+    end
 
     # Main entry point for DSL - builds simple multi-agent swarms
     #
@@ -179,6 +418,11 @@ module SwarmSDK
     #
     # @param yaml_content [String] YAML configuration content
     # @param base_dir [String, Pathname] Base directory for resolving agent file paths (default: Dir.pwd)
+    # @param allow_filesystem_tools [Boolean, nil] Whether to allow filesystem tools (nil uses global setting)
+    # @param env_interpolation [Boolean, nil] Whether to interpolate environment variables.
+    #   When nil, uses the global SwarmSDK.config.env_interpolation setting.
+    #   When true, interpolates ${VAR} and ${VAR:=default} patterns.
+    #   When false, skips interpolation entirely.
     # @return [Swarm, Workflow] Configured swarm or workflow instance
     # @raise [ConfigurationError] If YAML is invalid or configuration is incorrect
     #
@@ -201,8 +445,11 @@ module SwarmSDK
     # @example Load with default base_dir (Dir.pwd)
     #   yaml = File.read("config.yml")
     #   swarm = SwarmSDK.load(yaml)  # base_dir defaults to Dir.pwd
-    def load(yaml_content, base_dir: Dir.pwd, allow_filesystem_tools: nil)
-      config = Configuration.new(yaml_content, base_dir: base_dir)
+    #
+    # @example Load without environment variable interpolation
+    #   swarm = SwarmSDK.load(yaml, env_interpolation: false)
+    def load(yaml_content, base_dir: Dir.pwd, allow_filesystem_tools: nil, env_interpolation: nil)
+      config = Configuration.new(yaml_content, base_dir: base_dir, env_interpolation: env_interpolation)
       config.load_and_validate
       swarm = config.to_swarm(allow_filesystem_tools: allow_filesystem_tools)
 
@@ -224,6 +471,11 @@ module SwarmSDK
     # loading swarms from configuration files.
     #
     # @param path [String, Pathname] Path to YAML configuration file
+    # @param allow_filesystem_tools [Boolean, nil] Whether to allow filesystem tools (nil uses global setting)
+    # @param env_interpolation [Boolean, nil] Whether to interpolate environment variables.
+    #   When nil, uses the global SwarmSDK.config.env_interpolation setting.
+    #   When true, interpolates ${VAR} and ${VAR:=default} patterns.
+    #   When false, skips interpolation entirely.
     # @return [Swarm, Workflow] Configured swarm or workflow instance
     # @raise [ConfigurationError] If file not found or configuration invalid
     #
@@ -233,8 +485,11 @@ module SwarmSDK
     #
     # @example With absolute path
     #   swarm = SwarmSDK.load_file("/absolute/path/config.yml")
-    def load_file(path, allow_filesystem_tools: nil)
-      config = Configuration.load_file(path)
+    #
+    # @example Load without environment variable interpolation
+    #   swarm = SwarmSDK.load_file("config.yml", env_interpolation: false)
+    def load_file(path, allow_filesystem_tools: nil, env_interpolation: nil)
+      config = Configuration.load_file(path, env_interpolation: env_interpolation)
       swarm = config.to_swarm(allow_filesystem_tools: allow_filesystem_tools)
 
       # Apply hooks if any are configured (YAML-only feature)
@@ -248,21 +503,6 @@ module SwarmSDK
       swarm
     end
 
-    # Configure SwarmSDK global settings
-    def configure
-      self.settings ||= Settings.new
-      yield(settings)
-    end
-
-    # Reset settings to defaults
-    def reset_settings!
-      self.settings = Settings.new
-    end
-
-    # Alias for backward compatibility
-    alias_method :configuration, :settings
-    alias_method :reset_configuration!, :reset_settings!
-
     private
 
     # Check if hooks are configured in the configuration
@@ -437,88 +677,4 @@ module SwarmSDK
       error_hash.compact
     end
   end
-
-  # Settings class for SwarmSDK global settings (not to be confused with Configuration for YAML loading)
-  class Settings
-    # WebFetch tool LLM processing configuration
-    attr_accessor :webfetch_provider, :webfetch_model, :webfetch_base_url, :webfetch_max_tokens
-
-    # Filesystem tools control
-    attr_accessor :allow_filesystem_tools
-
-    def initialize
-      @webfetch_provider = nil
-      @webfetch_model = nil
-      @webfetch_base_url = nil
-      @webfetch_max_tokens = 4096
-      @allow_filesystem_tools = parse_env_bool("SWARM_SDK_ALLOW_FILESYSTEM_TOOLS", default: true)
-    end
-
-    # Check if WebFetch LLM processing is enabled
-    def webfetch_llm_enabled?
-      !@webfetch_provider.nil? && !@webfetch_model.nil?
-    end
-
-    private
-
-    def parse_env_bool(key, default:)
-      return default unless ENV.key?(key)
-
-      value = ENV[key].to_s.downcase
-      return true if ["true", "yes", "1", "on", "enabled"].include?(value)
-      return false if ["false", "no", "0", "off", "disabled"].include?(value)
-
-      default
-    end
-  end
-
-  # Initialize default settings
-  self.settings = Settings.new
-end
-
-# Automatically configure RubyLLM from environment variables
-# This makes SwarmSDK "just work" when users set standard ENV variables
-RubyLLM.configure do |config|
-  # Only set if config not already set (||= handles nil ENV values gracefully)
-
-  # OpenAI
-  config.openai_api_key ||= ENV["OPENAI_API_KEY"]
-  config.openai_api_base ||= ENV["OPENAI_API_BASE"]
-  config.openai_organization_id ||= ENV["OPENAI_ORG_ID"]
-  config.openai_project_id ||= ENV["OPENAI_PROJECT_ID"]
-
-  # Anthropic
-  config.anthropic_api_key ||= ENV["ANTHROPIC_API_KEY"]
-
-  # Google Gemini
-  config.gemini_api_key ||= ENV["GEMINI_API_KEY"]
-
-  # Google Vertex AI (note: vertexai, not vertex_ai)
-  config.vertexai_project_id ||= ENV["GOOGLE_CLOUD_PROJECT"] || ENV["VERTEXAI_PROJECT_ID"]
-  config.vertexai_location ||= ENV["GOOGLE_CLOUD_LOCATION"] || ENV["VERTEXAI_LOCATION"]
-
-  # DeepSeek
-  config.deepseek_api_key ||= ENV["DEEPSEEK_API_KEY"]
-
-  # Mistral
-  config.mistral_api_key ||= ENV["MISTRAL_API_KEY"]
-
-  # Perplexity
-  config.perplexity_api_key ||= ENV["PERPLEXITY_API_KEY"]
-
-  # OpenRouter
-  config.openrouter_api_key ||= ENV["OPENROUTER_API_KEY"]
-
-  # AWS Bedrock
-  config.bedrock_api_key ||= ENV["AWS_ACCESS_KEY_ID"]
-  config.bedrock_secret_key ||= ENV["AWS_SECRET_ACCESS_KEY"]
-  config.bedrock_region ||= ENV["AWS_REGION"]
-  config.bedrock_session_token ||= ENV["AWS_SESSION_TOKEN"]
-
-  # Ollama (local)
-  config.ollama_api_base ||= ENV["OLLAMA_API_BASE"]
-
-  # GPUStack (local)
-  config.gpustack_api_base ||= ENV["GPUSTACK_API_BASE"]
-  config.gpustack_api_key ||= ENV["GPUSTACK_API_KEY"]
 end

data/swarm_cli.gemspec

@@ -36,7 +36,7 @@ Gem::Specification.new do |spec|
 
   spec.add_dependency("fast-mcp", "~> 1.6")
   spec.add_dependency("pastel")
-  spec.add_dependency("swarm_sdk", "~> 2.2")
+  spec.add_dependency("swarm_sdk", "~> 2.5.1")
   spec.add_dependency("tty-box")
   spec.add_dependency("tty-cursor")
   spec.add_dependency("tty-link")

data/swarm_memory.gemspec

@@ -14,7 +14,12 @@ Gem::Specification.new do |spec|
   spec.metadata["source_code_uri"] = "https://github.com/parruda/claude-swarm"
   spec.metadata["changelog_uri"] = "https://github.com/parruda/claude-swarm/blob/main/docs/v2/CHANGELOG.swarm_memory.md"
 
-  spec.files         = Dir["lib/**/*", "LICENSE"]
+  spec.files = IO.popen(["git", "ls-files", "-z"], chdir: __dir__, err: IO::NULL) do |ls|
+    ls.readlines("\x0", chomp: true).select do |f|
+      (f == "lib/swarm_memory.rb") ||
+        f.match?(%r{\Alib/swarm_memory/}) || (f == "LICENSE")
+    end
+  end
   spec.require_paths = ["lib"]
   spec.required_ruby_version = ">= 3.2.0"
 
@@ -22,7 +27,7 @@ Gem::Specification.new do |spec|
   spec.add_dependency("async", "~> 2.0")
   spec.add_dependency("informers", "~> 1.2.1")
   spec.add_dependency("rice", "~> 4.6.0")
-  spec.add_dependency("ruby_llm_swarm", "~> 1.9.2")
-  spec.add_dependency("swarm_sdk", "~> 2.2")
+  spec.add_dependency("ruby_llm_swarm", "~> 1.9.5")
+  spec.add_dependency("swarm_sdk", "~> 2.5.1")
   spec.add_dependency("zeitwerk", "~> 2.6")
 end

data/swarm_sdk.gemspec

@@ -23,11 +23,10 @@ Gem::Specification.new do |spec|
   spec.metadata["source_code_uri"] = "https://github.com/parruda/claude-swarm"
   spec.metadata["changelog_uri"] = "https://github.com/parruda/claude-swarm/blob/main/docs/v2/CHANGELOG.swarm_sdk.md"
 
-  File.basename(__FILE__)
   spec.files = IO.popen(["git", "ls-files", "-z"], chdir: __dir__, err: IO::NULL) do |ls|
     ls.readlines("\x0", chomp: true).select do |f|
       (f == "lib/swarm_sdk.rb") ||
-        f.match?(%r{\Alib/swarm_sdk/})
+        f.match?(%r{\Alib/swarm_sdk/}) || (f == "LICENSE")
     end
   end
   # spec.bindir = "exe"
@@ -37,7 +36,8 @@ Gem::Specification.new do |spec|
   spec.add_dependency("async", "~> 2.0")
   spec.add_dependency("async-http-faraday", "~> 0.22")
   spec.add_dependency("faraday-follow_redirects", "~> 0.4")
-  spec.add_dependency("ruby_llm-mcp", "~> 0.8")
-  spec.add_dependency("ruby_llm_swarm", "~> 1.9.2")
+  spec.add_dependency("openssl", "~> 3.3.2")
+  spec.add_dependency("ruby_llm_swarm", "~> 1.9.5")
+  spec.add_dependency("ruby_llm_swarm-mcp", "~> 0.8.1")
   spec.add_dependency("zeitwerk", "~> 2.6")
 end