swarm_cli 2.0.0.pre.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 796c9d34130105fe9e4a2d6896fa01e5ec73222f7c334e430b5c2d736055905e
+  data.tar.gz: a9abe83f5e316339e27ea9d2ca52fcffbb29d0c0efcc20dd98ba6131cf2ee2e7
+SHA512:
+  metadata.gz: 87f901492c2bc58b85b64e4a06e925eed25629e69b4732acbb07056211cb2920f65fd4c79f8305720c4cd62bac49dd20436e16864dd713ba89c6f9b922aae1f2
+  data.tar.gz: 0b7f8c5736f63f5c427a60a530f88f32939c654d2a2295313152b70235e95d06f3288d3ede7576b5f9f6e13f7cf2c4e12340d0d2cbf83d278c81e6f927484983

data/exe/swarm

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "swarm_cli"
+
+SwarmCLI::CLI.start(ARGV)

data/lib/swarm_cli/cli.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+module SwarmCLI
+  class CLI
+    class << self
+      def start(args)
+        SwarmSDK.refresh_models_silently
+        new(args).run
+      end
+    end
+
+    def initialize(args)
+      @args = args
+    end
+
+    def run
+      # Handle special cases first
+      if @args.empty? || @args.include?("--help") || @args.include?("-h")
+        print_help
+        exit(0)
+      end
+
+      if @args.include?("--version") || @args.include?("-v")
+        print_version
+        exit(0)
+      end
+
+      # Extract command
+      command = @args.first
+
+      # Route to command
+      case command
+      when "run"
+        run_command(@args[1..])
+      when "mcp"
+        mcp_command(@args[1..])
+      else
+        $stderr.puts "Unknown command: #{command}"
+        $stderr.puts
+        print_help
+        exit(1)
+      end
+    rescue StandardError => e
+      $stderr.puts "Fatal error: #{e.message}"
+      exit(1)
+    end
+
+    private
+
+    def mcp_command(args)
+      # MCP has subcommands
+      subcommand = args.first
+
+      case subcommand
+      when "serve"
+        mcp_serve_command(args[1..])
+      when "tools"
+        mcp_tools_command(args[1..])
+      else
+        $stderr.puts "Unknown mcp subcommand: #{subcommand}"
+        $stderr.puts
+        $stderr.puts "Available mcp subcommands:"
+        $stderr.puts "  serve     Start an MCP server exposing swarm lead agent"
+        $stderr.puts "  tools     Start an MCP server exposing SwarmSDK tools"
+        exit(1)
+      end
+    end
+
+    def mcp_serve_command(args)
+      # Parse options
+      options = McpServeOptions.new
+      options.parse(args)
+
+      # Execute mcp serve command
+      Commands::McpServe.new(options).execute
+    rescue TTY::Option::InvalidParameter, TTY::Option::InvalidArgument => e
+      $stderr.puts "Error: #{e.message}"
+      $stderr.puts
+      $stderr.puts options.help
+      exit(1)
+    end
+
+    def mcp_tools_command(args)
+      # Parse options
+      options = McpToolsOptions.new
+      options.parse(args)
+
+      # Execute mcp tools command
+      Commands::McpTools.new(options).execute
+    rescue TTY::Option::InvalidParameter, TTY::Option::InvalidArgument => e
+      $stderr.puts "Error: #{e.message}"
+      $stderr.puts
+      $stderr.puts options.help
+      exit(1)
+    end
+
+    def run_command(args)
+      # Parse options
+      options = Options.new
+      options.parse(args)
+
+      # Execute run command
+      Commands::Run.new(options).execute
+    rescue TTY::Option::InvalidParameter, TTY::Option::InvalidArgument => e
+      $stderr.puts "Error: #{e.message}"
+      $stderr.puts
+      $stderr.puts options.help
+      exit(1)
+    end
+
+    def print_help
+      puts
+      puts "SwarmCLI v#{VERSION} - AI Agent Orchestration"
+      puts
+      puts "Usage:"
+      puts "  swarm run CONFIG_FILE -p PROMPT [options]"
+      puts "  swarm mcp serve CONFIG_FILE"
+      puts "  swarm mcp tools [TOOL_NAMES...]"
+      puts
+      puts "Commands:"
+      puts "  run           Execute a swarm with AI agents"
+      puts "  mcp serve     Start an MCP server exposing swarm lead agent"
+      puts "  mcp tools     Start an MCP server exposing SwarmSDK tools"
+      puts
+      puts "Options:"
+      puts "  -p, --prompt PROMPT          Task prompt for the swarm"
+      puts "  --output-format FORMAT       Output format: 'human' or 'json' (default: human)"
+      puts "  -q, --quiet                  Suppress progress output (human format only)"
+      puts "  --truncate                   Truncate long outputs for concise view"
+      puts "  --verbose                    Show system reminders and additional debug information"
+      puts "  -h, --help                   Print help"
+      puts "  -v, --version                Print version"
+      puts
+      puts "Examples:"
+      puts "  swarm run team.yml -p 'Build a REST API'"
+      puts "  echo 'Build a REST API' | swarm run team.yml"
+      puts "  swarm run team.yml -p 'Refactor code' --output-format json"
+      puts "  swarm mcp serve team.yml"
+      puts "  swarm mcp tools                              # Expose all SwarmSDK tools"
+      puts "  swarm mcp tools Bash Grep Read               # Space-separated tools"
+      puts "  swarm mcp tools ScratchpadWrite,ScratchpadRead  # Comma-separated tools"
+      puts
+    end
+
+    def print_version
+      puts "SwarmCLI v#{VERSION}"
+    end
+  end
+end

data/lib/swarm_cli/commands/mcp_serve.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module SwarmCLI
+  module Commands
+    # McpServe command starts an MCP server that exposes the swarm's lead agent as a tool.
+    #
+    # Usage:
+    #   swarm mcp serve config.yml
+    #
+    # The server uses stdio transport and exposes a "swarm" tool that executes tasks
+    # through the configured lead agent.
+    class McpServe
+      attr_reader :options
+
+      def initialize(options)
+        @options = options
+      end
+
+      def execute
+        # Validate options
+        options.validate!
+
+        # Load swarm configuration to validate it
+        config_path = options.config_file
+        unless File.exist?(config_path)
+          $stderr.puts "Error: Configuration file not found: #{config_path}"
+          exit(1)
+        end
+
+        # Validate the swarm configuration
+        begin
+          SwarmSDK::Swarm.load(config_path)
+        rescue SwarmSDK::ConfigurationError => e
+          $stderr.puts "Error: Invalid swarm configuration: #{e.message}"
+          exit(1)
+        end
+
+        # MCP servers should be quiet - stdout is reserved for MCP protocol
+        # Errors will still be logged to stderr
+
+        # Start the MCP server
+        start_mcp_server(config_path)
+      rescue Interrupt
+        # User cancelled (Ctrl+C) - silent exit
+        exit(130)
+      rescue StandardError => e
+        # Unexpected errors - always log to stderr
+        $stderr.puts "Fatal error: #{e.message}"
+        $stderr.puts e.backtrace.first(5).join("\n") if ENV["DEBUG"]
+        exit(1)
+      end
+
+      private
+
+      def start_mcp_server(config_path)
+        require "fast_mcp"
+
+        # Create the server
+        server = FastMcp::Server.new(
+          name: "swarm-mcp-server",
+          version: SwarmCLI::VERSION,
+        )
+
+        # Register the swarm tool
+        tool_class = create_swarm_tool_class(config_path)
+        server.register_tool(tool_class)
+
+        # Start with stdio transport (default)
+        server.start
+      end
+
+      def create_swarm_tool_class(config_path)
+        # Create a tool class dynamically with the config path bound
+        Class.new(FastMcp::Tool) do
+          # Explicit tool name required for anonymous classes
+          tool_name "task"
+
+          description "Execute tasks through the SwarmSDK lead agent"
+
+          arguments do
+            required(:task).filled(:string).description("The task or prompt to execute")
+            optional(:description).filled(:string).description("Brief description of the task")
+            optional(:thinking_budget).filled(:string, included_in?: ["think", "think hard", "think harder", "ultrathink"]).description("Thinking budget level")
+          end
+
+          # Store config path as class variable
+          @config_path = config_path
+
+          class << self
+            attr_accessor :config_path
+          end
+
+          define_method(:call) do |task:, description: nil, thinking_budget: nil|
+            # Load swarm for each execution (ensures fresh state)
+            swarm = SwarmSDK::Swarm.load(self.class.config_path)
+
+            # Build prompt with thinking budget if provided
+            prompt = task
+            if thinking_budget
+              prompt = "<thinking_budget>#{thinking_budget}</thinking_budget>\n\n#{task}"
+            end
+
+            # Execute the task (description is metadata only, not passed to execute)
+            result = swarm.execute(prompt)
+
+            # Check for errors
+            if result.failure?
+              {
+                success: false,
+                error: result.error.message,
+                task: task,
+                description: description,
+              }
+            else
+              # On success, return just the content string
+              result.content
+            end
+          rescue StandardError => e
+            {
+              success: false,
+              error: e.message,
+              task: task,
+              description: description,
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/swarm_cli/commands/mcp_tools.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+module SwarmCLI
+  module Commands
+    # McpTools command starts an MCP server that exposes SwarmSDK tools.
+    #
+    # Usage:
+    #   swarm mcp tools              # Expose all available tools
+    #   swarm mcp tools Bash Grep    # Expose only Bash and Grep
+    #
+    # The server uses stdio transport and exposes SwarmSDK tools as MCP tools.
+    class McpTools
+      attr_reader :options
+
+      def initialize(options)
+        @options = options
+        @scratchpad = SwarmSDK::Scratchpad.new
+      end
+
+      def execute
+        # Validate options
+        options.validate!
+
+        # Determine which tools to expose
+        tools_to_expose = determine_tools
+
+        if tools_to_expose.empty?
+          $stderr.puts "Error: No tools available to expose"
+          exit(1)
+        end
+
+        # Start the MCP server
+        start_mcp_server(tools_to_expose)
+      rescue Interrupt
+        # User cancelled (Ctrl+C) - silent exit
+        exit(130)
+      rescue StandardError => e
+        # Unexpected errors - always log to stderr
+        $stderr.puts "Fatal error: #{e.message}"
+        $stderr.puts e.backtrace.first(5).join("\n") if ENV["DEBUG"]
+        exit(1)
+      end
+
+      private
+
+      def determine_tools
+        if options.tool_names.any?
+          # Use specified tools
+          options.tool_names.map(&:to_sym)
+        else
+          # Default: expose all available tools
+          SwarmSDK::Tools::Registry.available_names
+        end
+      end
+
+      def start_mcp_server(tool_names)
+        require "fast_mcp"
+
+        # Create the server
+        server = FastMcp::Server.new(
+          name: "swarm-tools-server",
+          version: SwarmCLI::VERSION,
+        )
+
+        # Register each tool
+        tool_names.each do |tool_name|
+          tool_class = create_mcp_tool_wrapper(tool_name)
+          server.register_tool(tool_class)
+        end
+
+        # Start with stdio transport (default)
+        server.start
+      end
+
+      def create_special_tool_instance(tool_name)
+        case tool_name
+        when :Read
+          SwarmSDK::Tools::Read.create_for_agent(:mcp)
+        when :Write
+          SwarmSDK::Tools::Write.create_for_agent(:mcp)
+        when :Edit
+          SwarmSDK::Tools::Edit.create_for_agent(:mcp)
+        when :MultiEdit
+          SwarmSDK::Tools::MultiEdit.create_for_agent(:mcp)
+        when :TodoWrite
+          SwarmSDK::Tools::TodoWrite.create_for_agent(:mcp)
+        when :ScratchpadWrite
+          SwarmSDK::Tools::ScratchpadWrite.create_for_scratchpad(@scratchpad)
+        when :ScratchpadRead
+          SwarmSDK::Tools::ScratchpadRead.create_for_scratchpad(@scratchpad)
+        when :ScratchpadList
+          SwarmSDK::Tools::ScratchpadList.create_for_scratchpad(@scratchpad)
+        else
+          raise "Unknown special tool: #{tool_name}"
+        end
+      end
+
+      def create_mcp_tool_wrapper(tool_name)
+        sdk_tool_class_or_special = SwarmSDK::Tools::Registry.get(tool_name)
+
+        # Get the actual tool instance for special tools
+        sdk_tool = if sdk_tool_class_or_special == :special
+          create_special_tool_instance(tool_name)
+        else
+          sdk_tool_class_or_special.new
+        end
+
+        # Get tool metadata
+        tool_description = sdk_tool.respond_to?(:description) ? sdk_tool.description : "SwarmSDK #{tool_name} tool"
+        tool_params = sdk_tool.class.respond_to?(:parameters) ? sdk_tool.class.parameters : {}
+
+        # Create an MCP tool wrapper
+        Class.new(FastMcp::Tool) do
+          tool_name tool_name.to_s
+          description tool_description
+
+          # Map RubyLLM parameters to fast-mcp arguments
+          arguments do
+            tool_params.each do |param_name, param_obj|
+              param_type = param_obj.type == "integer" ? :integer : :string
+              if param_obj.required
+                required(param_name).filled(param_type).description(param_obj.description || "")
+              else
+                optional(param_name).filled(param_type).description(param_obj.description || "")
+              end
+            end
+          end
+
+          # Capture sdk_tool in closure
+          define_method(:call) do |**kwargs|
+            result = sdk_tool.execute(**kwargs)
+
+            # Return string output for MCP
+            if result.is_a?(Hash)
+              result[:output] || result[:content] || result[:files]&.join("\n") || result.to_s
+            else
+              result.to_s
+            end
+          rescue StandardError => e
+            "Error: #{e.message}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/swarm_cli/commands/run.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module SwarmCLI
+  module Commands
+    # Run command executes a swarm with the given configuration and prompt.
+    #
+    # Usage:
+    #   swarm run config.yml -p "Build a REST API"
+    #   echo "Build a REST API" | swarm run config.yml
+    #   swarm run config.yml -p "Task" --output-format json
+    #
+    class Run
+      attr_reader :options
+
+      def initialize(options)
+        @options = options
+      end
+
+      def execute
+        # Validate options
+        options.validate!
+
+        # Load swarm configuration
+        swarm = load_swarm
+
+        # Create formatter based on output format
+        formatter = create_formatter
+
+        # Get prompt text
+        prompt = options.prompt_text
+
+        # Notify formatter of start
+        formatter.on_start(
+          config_path: options.config_file,
+          swarm_name: swarm.name,
+          lead_agent: swarm.lead_agent,
+          prompt: prompt,
+        )
+
+        # Execute swarm with logging
+        start_time = Time.now
+        result = swarm.execute(prompt) do |log_entry|
+          formatter.on_log(log_entry)
+        end
+
+        # Check for errors
+        if result.failure?
+          duration = Time.now - start_time
+          formatter.on_error(error: result.error, duration: duration)
+          exit(1)
+        end
+
+        # Notify formatter of success
+        formatter.on_success(result: result)
+
+        # Exit successfully
+        exit(0)
+      rescue SwarmSDK::ConfigurationError, SwarmSDK::AgentNotFoundError => e
+        # Configuration errors - show user-friendly message
+        handle_error(e, formatter: create_formatter)
+        exit(1)
+      rescue SwarmCLI::ExecutionError => e
+        # CLI-specific errors (e.g., missing prompt)
+        handle_error(e, formatter: create_formatter)
+        exit(1)
+      rescue Interrupt
+        # User cancelled (Ctrl+C)
+        $stderr.puts "\n\nExecution cancelled by user"
+        exit(130)
+      rescue StandardError => e
+        # Unexpected errors
+        handle_error(e, formatter: create_formatter)
+        exit(1)
+      end
+
+      private
+
+      def load_swarm
+        config_path = options.config_file
+
+        unless File.exist?(config_path)
+          raise SwarmCLI::ExecutionError, "Configuration file not found: #{config_path}"
+        end
+
+        SwarmSDK::Swarm.load(config_path)
+      rescue SwarmSDK::ConfigurationError => e
+        # Re-raise with more context
+        raise SwarmCLI::ExecutionError, "Configuration error: #{e.message}"
+      end
+
+      def create_formatter
+        case options.output_format
+        when "json"
+          Formatters::JsonFormatter.new
+        when "human"
+          Formatters::HumanFormatter.new(
+            quiet: options.quiet?,
+            truncate: options.truncate?,
+            verbose: options.verbose?,
+          )
+        else
+          raise SwarmCLI::ExecutionError, "Unknown output format: #{options.output_format}"
+        end
+      end
+
+      def handle_error(error, formatter: nil)
+        if formatter
+          formatter.on_error(error: error)
+        else
+          # Fallback if formatter not available
+          $stderr.puts "Error: #{error.message}"
+        end
+      end
+    end
+  end
+end