swarm_sdk 2.7.13 → 3.0.0.alpha1

data/lib/swarm_sdk/swarm_loader.rb

@@ -1,145 +0,0 @@
-# frozen_string_literal: true
-
-module SwarmSDK
-  # Loader for creating swarm instances from multiple sources
-  #
-  # SwarmLoader loads swarm configurations from:
-  # - Files: .rb (DSL) or .yml (YAML)
-  # - YAML strings: Direct YAML content
-  # - DSL blocks: Inline Ruby blocks
-  #
-  # All loaded swarms get hierarchical swarm_id and parent_swarm_id.
-  #
-  # ## Features
-  # - Supports Ruby DSL (.rb files or blocks)
-  # - Supports YAML (.yml/.yaml files or strings)
-  # - Sets hierarchical swarm_id based on parent + registration name
-  # - Isolates loading in separate context
-  # - Proper error handling for missing/invalid sources
-  #
-  # ## Examples
-  #
-  #   # From file
-  #   swarm = SwarmLoader.load_from_file(
-  #     "./swarms/code_review.rb",
-  #     swarm_id: "main/code_review",
-  #     parent_swarm_id: "main"
-  #   )
-  #
-  #   # From YAML string
-  #   swarm = SwarmLoader.load_from_yaml_string(
-  #     "version: 2\nswarm:\n  name: Test\n...",
-  #     swarm_id: "main/testing",
-  #     parent_swarm_id: "main"
-  #   )
-  #
-  #   # From block
-  #   swarm = SwarmLoader.load_from_block(
-  #     proc { id "team"; name "Team"; agent :dev { ... } },
-  #     swarm_id: "main/team",
-  #     parent_swarm_id: "main"
-  #   )
-  #
-  class SwarmLoader
-    class << self
-      # Load a swarm from a file (.rb or .yml)
-      #
-      # @param file_path [String] Path to swarm file
-      # @param swarm_id [String] Hierarchical swarm ID to assign
-      # @param parent_swarm_id [String] Parent swarm ID
-      # @return [Swarm] Loaded swarm instance with overridden IDs
-      # @raise [ConfigurationError] If file not found or unsupported type
-      def load_from_file(file_path, swarm_id:, parent_swarm_id:)
-        path = Pathname.new(file_path).expand_path
-
-        raise ConfigurationError, "Swarm file not found: #{path}" unless path.exist?
-
-        # Determine file type and load
-        case path.extname
-        when ".rb"
-          load_from_ruby_file(path, swarm_id, parent_swarm_id)
-        when ".yml", ".yaml"
-          load_from_yaml_file(path, swarm_id, parent_swarm_id)
-        else
-          raise ConfigurationError, "Unsupported swarm file type: #{path.extname}. Use .rb, .yml, or .yaml"
-        end
-      end
-
-      # Load a swarm from YAML string
-      #
-      # @param yaml_content [String] YAML configuration content
-      # @param swarm_id [String] Hierarchical swarm ID to assign
-      # @param parent_swarm_id [String] Parent swarm ID
-      # @return [Swarm] Loaded swarm instance with overridden IDs
-      # @raise [ConfigurationError] If YAML is invalid
-      def load_from_yaml_string(yaml_content, swarm_id:, parent_swarm_id:)
-        # Use Configuration to parse YAML string
-        config = Configuration.new(yaml_content, base_dir: Dir.pwd)
-        config.load_and_validate
-        swarm = config.to_swarm
-
-        # Override swarm_id and parent_swarm_id
-        swarm.override_swarm_ids(swarm_id: swarm_id, parent_swarm_id: parent_swarm_id)
-
-        swarm
-      end
-
-      # Load a swarm from DSL block
-      #
-      # @param block [Proc] Block containing SwarmSDK DSL
-      # @param swarm_id [String] Hierarchical swarm ID to assign
-      # @param parent_swarm_id [String] Parent swarm ID
-      # @return [Swarm] Loaded swarm instance with overridden IDs
-      def load_from_block(block, swarm_id:, parent_swarm_id:)
-        # Execute block in Builder context
-        builder = Swarm::Builder.new
-        builder.instance_eval(&block)
-        swarm = builder.build_swarm
-
-        # Override swarm_id and parent_swarm_id
-        swarm.override_swarm_ids(swarm_id: swarm_id, parent_swarm_id: parent_swarm_id)
-
-        swarm
-      end
-
-      private
-
-      # Load swarm from Ruby DSL file
-      #
-      # @param path [Pathname] Path to .rb file
-      # @param swarm_id [String] Swarm ID to assign
-      # @param parent_swarm_id [String] Parent swarm ID
-      # @return [Swarm] Loaded swarm with overridden IDs
-      def load_from_ruby_file(path, swarm_id, parent_swarm_id)
-        content = File.read(path)
-
-        # Execute DSL in isolated context
-        # The DSL should return a swarm via SwarmSDK.build { ... }
-        swarm = eval(content, binding, path.to_s) # rubocop:disable Security/Eval
-
-        # Override swarm_id and parent_swarm_id
-        # These must be set after build to ensure hierarchical structure
-        swarm.override_swarm_ids(swarm_id: swarm_id, parent_swarm_id: parent_swarm_id)
-
-        swarm
-      end
-
-      # Load swarm from YAML file
-      #
-      # @param path [Pathname] Path to .yml file
-      # @param swarm_id [String] Swarm ID to assign
-      # @param parent_swarm_id [String] Parent swarm ID
-      # @return [Swarm] Loaded swarm with overridden IDs
-      def load_from_yaml_file(path, swarm_id, parent_swarm_id)
-        # Use Configuration to load and convert YAML to swarm
-        config = Configuration.load_file(path.to_s)
-        swarm = config.to_swarm
-
-        # Override swarm_id and parent_swarm_id
-        swarm.override_swarm_ids(swarm_id: swarm_id, parent_swarm_id: parent_swarm_id)
-
-        swarm
-      end
-    end
-  end
-end

data/lib/swarm_sdk/swarm_registry.rb

@@ -1,136 +0,0 @@
-# frozen_string_literal: true
-
-module SwarmSDK
-  # Registry for managing sub-swarms in composable swarms
-  #
-  # SwarmRegistry handles lazy loading, caching, and lifecycle management
-  # of child swarms registered via the `swarms` DSL block.
-  #
-  # ## Features
-  # - Lazy loading: Sub-swarms are only loaded when first accessed
-  # - Caching: Loaded swarms are cached for reuse
-  # - Hierarchical IDs: Sub-swarms get IDs based on parent + registration name
-  # - Context control: keep_context determines if swarm state persists
-  # - Lifecycle management: Cleanup cascades through all sub-swarms
-  #
-  # ## Example
-  #
-  #   registry = SwarmRegistry.new(parent_swarm_id: "main_app")
-  #   registry.register("code_review", file: "./swarms/code_review.rb", keep_context: true)
-  #
-  #   # Lazy load on first access
-  #   swarm = registry.load_swarm("code_review")
-  #   # => Swarm with swarm_id = "main_app/code_review"
-  #
-  #   # Reset if keep_context: false
-  #   registry.reset_if_needed("code_review")
-  #
-  class SwarmRegistry
-    # Initialize a new swarm registry
-    #
-    # @param parent_swarm_id [String] ID of the parent swarm
-    def initialize(parent_swarm_id:)
-      @parent_swarm_id = parent_swarm_id
-      @registered_swarms = {}
-      # Format: { "code_review" => { file: "...", keep_context: true, instance: nil } }
-    end
-
-    # Register a sub-swarm for lazy loading
-    #
-    # @param name [String] Registration name for the swarm
-    # @param source [Hash] Source specification with :type and :value
-    #   - { type: :file, value: "./path/to/swarm.rb" }
-    #   - { type: :yaml, value: "version: 2\n..." }
-    #   - { type: :block, value: Proc }
-    # @param keep_context [Boolean] Whether to preserve conversation state between calls (default: true)
-    # @return [void]
-    # @raise [ArgumentError] If swarm with same name already registered
-    def register(name, source:, keep_context: true)
-      raise ArgumentError, "Swarm '#{name}' already registered" if @registered_swarms.key?(name)
-
-      @registered_swarms[name] = {
-        source: source,
-        keep_context: keep_context,
-        instance: nil, # Lazy load
-      }
-    end
-
-    # Check if a swarm is registered
-    #
-    # @param name [String] Swarm registration name
-    # @return [Boolean] True if swarm is registered
-    def registered?(name)
-      @registered_swarms.key?(name)
-    end
-
-    # Load a registered swarm (lazy load + cache)
-    #
-    # Loads the swarm from its source (file, yaml, or block) on first access, then caches it.
-    # Sets hierarchical swarm_id based on parent_swarm_id + registration name.
-    #
-    # @param name [String] Swarm registration name
-    # @return [Swarm] Loaded swarm instance
-    # @raise [ConfigurationError] If swarm not registered
-    def load_swarm(name)
-      entry = @registered_swarms[name]
-      raise ConfigurationError, "Swarm '#{name}' not registered" unless entry
-
-      # Return cached instance if exists
-      return entry[:instance] if entry[:instance]
-
-      # Load from appropriate source
-      swarm_id = "#{@parent_swarm_id}/#{name}" # Hierarchical
-      source = entry[:source]
-
-      swarm = case source[:type]
-      when :file
-        SwarmLoader.load_from_file(
-          source[:value],
-          swarm_id: swarm_id,
-          parent_swarm_id: @parent_swarm_id,
-        )
-      when :yaml
-        SwarmLoader.load_from_yaml_string(
-          source[:value],
-          swarm_id: swarm_id,
-          parent_swarm_id: @parent_swarm_id,
-        )
-      when :block
-        SwarmLoader.load_from_block(
-          source[:value],
-          swarm_id: swarm_id,
-          parent_swarm_id: @parent_swarm_id,
-        )
-      else
-        raise ConfigurationError, "Unknown source type: #{source[:type]}"
-      end
-
-      entry[:instance] = swarm
-      swarm
-    end
-
-    # Reset swarm context if keep_context: false
-    #
-    # @param name [String] Swarm registration name
-    # @return [void]
-    def reset_if_needed(name)
-      entry = @registered_swarms[name]
-      return if entry[:keep_context]
-
-      entry[:instance]&.reset_context!
-    end
-
-    # Cleanup all registered swarms
-    #
-    # Stops all loaded swarm instances and clears the registry.
-    # Should be called when parent swarm is done.
-    #
-    # @return [void]
-    def shutdown_all
-      @registered_swarms.each_value do |entry|
-        entry[:instance]&.cleanup
-      end
-      @registered_swarms.clear
-    end
-  end
-end

data/lib/swarm_sdk/tools/base.rb

@@ -1,63 +0,0 @@
-# frozen_string_literal: true
-
-module SwarmSDK
-  module Tools
-    # Base class for all SwarmSDK tools
-    #
-    # Provides:
-    # - Declarative removability control
-    # - Common tool functionality
-    # - Standard initialization patterns
-    #
-    # ## Removability
-    #
-    # Tools can be marked as non-removable to ensure they're always available:
-    #
-    #   class Think < Base
-    #     removable false
-    #   end
-    #
-    # Non-removable tools are included even when skills specify a limited toolset.
-    #
-    # @example Removable tool (default)
-    #   class Read < Base
-    #     # removable true  # Default, can omit
-    #   end
-    #
-    # @example Non-removable tool
-    #   class Think < Base
-    #     removable false  # Always available
-    #   end
-    class Base < RubyLLM::Tool
-      class << self
-        # Whether this tool can be deactivated by LoadSkill
-        #
-        # Non-removable tools are ALWAYS active regardless of skill toolset.
-        # Use for essential tools that agents should never lose.
-        #
-        # @return [Boolean] True if removable (default: true)
-        def removable?
-          @removable.nil? ? true : @removable
-        end
-
-        # Mark tool as removable or non-removable
-        #
-        # @param value [Boolean] Whether tool can be removed
-        # @return [void]
-        #
-        # @example Make tool always available
-        #   removable false
-        def removable(value)
-          @removable = value
-        end
-      end
-
-      # Instance method for checking removability
-      #
-      # @return [Boolean]
-      def removable?
-        self.class.removable?
-      end
-    end
-  end
-end

data/lib/swarm_sdk/tools/bash.rb

@@ -1,280 +0,0 @@
-# frozen_string_literal: true
-
-module SwarmSDK
-  module Tools
-    # Bash tool for executing shell commands
-    #
-    # Executes commands in a persistent shell session with timeout support.
-    # Provides comprehensive guidance on proper usage patterns.
-    class Bash < Base
-      # Factory pattern: declare what parameters this tool needs for instantiation
-      class << self
-        def creation_requirements
-          [:directory]
-        end
-      end
-
-      def initialize(directory:)
-        super()
-        @directory = File.expand_path(directory)
-      end
-
-      def name
-        "Bash"
-      end
-
-      description <<~DESC
-        Executes a given bash command in a persistent shell session with optional timeout, ensuring proper handling and security measures.
-
-        IMPORTANT: This tool is for terminal operations like git, npm, docker, etc. DO NOT use it for file operations (reading, writing, editing, searching, finding files) - use the specialized tools for this instead.
-
-        Before executing the command, please follow these steps:
-
-        1. Directory Verification:
-           - If the command will create new directories or files, first use `ls` to verify the parent directory exists and is the correct location
-           - For example, before running "mkdir foo/bar", first use `ls foo` to check that "foo" exists and is the intended parent directory
-
-        2. Command Execution:
-           - Always quote file paths that contain spaces with double quotes (e.g., cd "path with spaces/file.txt")
-           - Examples of proper quoting:
-             - cd "/Users/name/My Documents" (correct)
-             - cd /Users/name/My Documents (incorrect - will fail)
-             - python "/path/with spaces/script.py" (correct)
-             - python /path/with spaces/script.py (incorrect - will fail)
-           - After ensuring proper quoting, execute the command.
-           - Capture the output of the command.
-
-        Usage notes:
-          - The command argument is required.
-          - You can specify an optional timeout in milliseconds (up to 600000ms / 10 minutes). If not specified, commands will timeout after 120000ms (2 minutes).
-          - It is very helpful if you write a clear, concise description of what this command does in 5-10 words.
-          - If the output exceeds 30000 characters, output will be truncated before being returned to you.
-          - Avoid using Bash with the `find`, `grep`, `cat`, `head`, `tail`, `sed`, `awk`, or `echo` commands, unless explicitly instructed or when these commands are truly necessary for the task. Instead, always prefer using the dedicated tools for these commands:
-            - File search: Use Glob (NOT find or ls)
-            - Content search: Use Grep (NOT grep or rg)
-            - Read files: Use Read (NOT cat/head/tail)
-            - Edit files: Use Edit (NOT sed/awk)
-            - Write files: Use Write (NOT echo >/cat <<EOF)
-            - Communication: Output text directly (NOT echo/printf)
-          - When issuing multiple commands:
-            - If the commands are independent and can run in parallel, make multiple Bash tool calls in a single message. For example, if you need to run "git status" and "git diff", send a single message with two Bash tool calls in parallel.
-            - If the commands depend on each other and must run sequentially, use a single Bash call with '&&' to chain them together (e.g., `git add . && git commit -m "message" && git push`). For instance, if one operation must complete before another starts (like mkdir before cp, Write before Bash for git operations, or git add before git commit), run these operations sequentially instead.
-            - Use ';' only when you need to run commands sequentially but don't care if earlier commands fail
-            - DO NOT use newlines to separate commands (newlines are ok in quoted strings)
-          - Try to maintain your current working directory throughout the session by using absolute paths and avoiding usage of `cd`. You may use `cd` if the User explicitly requests it.
-            <good-example>
-            pytest /foo/bar/tests
-            </good-example>
-            <bad-example>
-            cd /foo/bar && pytest tests
-            </bad-example>
-      DESC
-
-      param :command,
-        type: "string",
-        desc: "The command to execute",
-        required: true
-
-      param :description,
-        type: "string",
-        desc: "Clear, concise description of what this command does in 5-10 words, in active voice. Examples:\nInput: ls\nOutput: List files in current directory\n\nInput: git status\nOutput: Show working tree status\n\nInput: npm install\nOutput: Install package dependencies\n\nInput: mkdir foo\nOutput: Create directory 'foo'",
-        required: false
-
-      param :timeout,
-        type: "number",
-        desc: "Optional timeout in milliseconds (max 600000)",
-        required: false
-
-      # NOTE: Timeout and output limits now accessed via SwarmSDK.config
-
-      # Commands that are ALWAYS blocked for safety reasons
-      # These cannot be overridden by permissions configuration
-      ALWAYS_BLOCKED_COMMANDS = [
-        %r{^rm\s+-rf\s+/$}, # rm -rf / - delete root filesystem
-      ].freeze
-
-      def execute(command:, description: nil, timeout: nil)
-        # Validate inputs
-        return validation_error("command is required") if command.nil? || command.empty?
-
-        # Check against always-blocked commands
-        blocked_pattern = ALWAYS_BLOCKED_COMMANDS.find { |pattern| pattern.match?(command) }
-        if blocked_pattern
-          return blocked_command_error(command, blocked_pattern)
-        end
-
-        # Validate and set timeout
-        timeout_ms = timeout || SwarmSDK.config.bash_command_timeout
-        timeout_ms = [timeout_ms, SwarmSDK.config.bash_command_max_timeout].min
-        timeout_seconds = timeout_ms / 1000.0
-
-        # Execute command with timeout
-        stdout = +""
-        stderr = +""
-        exit_status = nil
-
-        begin
-          require "open3"
-          require "timeout"
-
-          Timeout.timeout(timeout_seconds) do
-            # CRITICAL: Change to agent's directory for subprocess
-            # This is SAFE because Open3.popen3 creates a subprocess
-            # The subprocess inherits the directory, but the parent fiber is unaffected
-            Dir.chdir(@directory) do
-              Open3.popen3(command) do |stdin, out, err, wait_thr|
-                stdin.close # Close stdin since we don't send input
-
-                # Read stdout and stderr
-                stdout = out.read || ""
-                stderr = err.read || ""
-                exit_status = wait_thr.value.exitstatus
-              end
-            end
-          end
-        rescue Timeout::Error
-          return format_timeout_error(command, timeout_seconds)
-        rescue Errno::ENOENT => e
-          return error("Command not found or executable not in PATH: #{e.message}")
-        rescue Errno::EACCES
-          return error("Permission denied: Cannot execute command '#{command}'")
-        rescue StandardError => e
-          return error("Failed to execute command: #{e.class.name} - #{e.message}")
-        end
-
-        # Build output
-        output = format_command_output(command, description, stdout, stderr, exit_status)
-
-        # Truncate if too long
-        max_output = SwarmSDK.config.output_character_limit
-        if output.length > max_output
-          truncated = output[0...max_output]
-          truncated += "\n\n<system-reminder>Output truncated at #{max_output} characters. The full output was #{output.length} characters.</system-reminder>"
-          output = truncated
-        end
-
-        # Add usage reminders for certain patterns
-        output = add_usage_reminders(output, command)
-
-        output
-      rescue StandardError => e
-        error("Unexpected error executing command: #{e.class.name} - #{e.message}")
-      end
-
-      private
-
-      def validation_error(message)
-        "<tool_use_error>InputValidationError: #{message}</tool_use_error>"
-      end
-
-      def error(message)
-        "Error: #{message}"
-      end
-
-      def blocked_command_error(command, pattern)
-        <<~ERROR
-          Error: Command blocked for safety reasons.
-          Command: #{command}
-          Pattern: #{pattern.source}
-
-          <system-reminder>
-          SECURITY BLOCK: This command is permanently blocked for safety reasons and cannot be executed.
-
-          This is a built-in safety feature of the Bash tool that cannot be overridden by any configuration.
-          The command matches a pattern that could cause catastrophic system damage.
-
-          DO NOT attempt to:
-          - Modify the command slightly to bypass this check
-          - Ask the user to allow this command
-          - Work around this restriction in any way
-
-          If you need to perform a similar operation safely, consider:
-          - Using a more specific path instead of system-wide operations
-          - Using dedicated tools for file operations
-          - Asking the user for guidance on a safer approach
-
-          This is an UNRECOVERABLE error. You must inform the user that this command cannot be executed for safety reasons.
-          </system-reminder>
-        ERROR
-      end
-
-      def format_timeout_error(command, timeout_seconds)
-        <<~ERROR
-          Error: Command timed out after #{timeout_seconds} seconds.
-          Command: #{command}
-
-          <system-reminder>The command exceeded the timeout limit. Consider:
-          1. Breaking the command into smaller steps
-          2. Increasing the timeout parameter
-          3. Running long-running commands in the background if supported
-          </system-reminder>
-        ERROR
-      end
-
-      def format_command_output(command, description, stdout, stderr, exit_status)
-        parts = []
-
-        # Add description if provided
-        parts << "Running: #{description}" if description
-
-        # Add command
-        parts << "$ #{command}"
-        parts << ""
-
-        # Add exit status
-        parts << "Exit code: #{exit_status}"
-
-        # Add stdout if present
-        if stdout && !stdout.empty?
-          parts << ""
-          parts << "STDOUT:"
-          parts << stdout.chomp
-        end
-
-        # Add stderr if present
-        if stderr && !stderr.empty?
-          parts << ""
-          parts << "STDERR:"
-          parts << stderr.chomp
-        end
-
-        # Add warning for non-zero exit
-        if exit_status != 0
-          parts << ""
-          parts << "<system-reminder>Command exited with non-zero status (#{exit_status}). Check STDERR for error details.</system-reminder>"
-        end
-
-        parts.join("\n")
-      end
-
-      def add_usage_reminders(output, command)
-        reminders = []
-
-        # Detect file operation commands that should use dedicated tools
-        if command.match?(/\b(cat|head|tail|less|more)\s+/)
-          reminders << "You used a command to read a file. Consider using the Read tool instead for better formatting and error handling."
-        end
-
-        if command.match?(/\b(grep|rg|ag)\s+/)
-          reminders << "You used grep/ripgrep to search files. Consider using the Grep tool instead for structured results."
-        end
-
-        if command.match?(/\b(find|locate)\s+/)
-          reminders << "You used find to locate files. Consider using the Glob tool instead for pattern-based file matching."
-        end
-
-        if command.match?(/\b(sed|awk)\s+/) && !command.include?("|")
-          reminders << "You used sed/awk for file editing. Consider using the Edit tool instead for safer, tracked file modifications."
-        end
-
-        if command.match?(/\becho\s+.*>\s*/) || command.match?(/\bcat\s*<</)
-          reminders << "You used echo/cat with redirection to write a file. Consider using the Write tool instead for proper file creation."
-        end
-
-        return output if reminders.empty?
-
-        output + "\n\n<system-reminder>\n#{reminders.join("\n\n")}\n</system-reminder>"
-      end
-    end
-  end
-end

data/lib/swarm_sdk/tools/clock.rb

@@ -1,46 +0,0 @@
-# frozen_string_literal: true
-
-module SwarmSDK
-  module Tools
-    # Clock tool provides current date and time information
-    #
-    # Returns current temporal information in a consistent format.
-    # Agents use this when they need to know what day/time it is.
-    class Clock < Base
-      removable false # Clock is always available
-
-      description <<~DESC
-        Get current date and time.
-
-        Returns:
-        - Current date (YYYY-MM-DD format)
-        - Current time (HH:MM:SS format)
-        - Day of week (Monday, Tuesday, etc.)
-        - ISO 8601 timestamp (full datetime)
-
-        Use this when you need to know what day it is, what time it is,
-        or to store temporal information (e.g., "As of 2025-10-20...").
-
-        No parameters needed - just call Clock() to get complete temporal information.
-      DESC
-
-      # No parameters needed
-
-      # Override name to return simple "Clock"
-      def name
-        "Clock"
-      end
-
-      def execute
-        now = Time.now
-
-        <<~RESULT.chomp
-          Current date: #{now.strftime("%Y-%m-%d")}
-          Current time: #{now.strftime("%H:%M:%S")}
-          Day of week: #{now.strftime("%A")}
-          ISO 8601: #{now.iso8601}
-        RESULT
-      end
-    end
-  end
-end