openbolt 5.3.0 → 5.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e9b0100076081c5483e86b98cea67dc2c9ed0a46ceb7b86d3883257f34b68ee8
-  data.tar.gz: c85b0fd26588f95757ebdf25b86ed39a3f2c16dc530b0517c4d4c6848e16440a
+  metadata.gz: af114a7662dadfeb0b7a3b93bade87bd679b4d555c718ef9de2782327fb72f94
+  data.tar.gz: 212b616948e0e548f821576db50971c21ad9f9e5e9a84d9e676542078ea623d3
 SHA512:
-  metadata.gz: 89b8e8179220b89ca34d44682c9a2e83723dfc7d06ffd09ed7bbaff010cb6e4635d837451f9131eea95917151b81c74e6f65912fd77c8cfc8d694e1748f236f9
-  data.tar.gz: 6158a6c97dad745b1ad1a0ec9a745bd44ce59f1a8ad0e636c3df2f39cd07f962b28a1a19d6109dc94d68c3938e18cb5acd498ceea12a3fff094327390ab776a8
+  metadata.gz: 9a85395239d2b5de8adc4d538bf0860139ee0585c3880d8ea6ccb46a840fa0ee6371e58ce17feb2cc171b5fc47cddeabd284adedcbb3abd60675951b1b5e0169
+  data.tar.gz: f42f2da1b4ea78080c3790e2165be94105bb7a9ad9c5a16b2702f5511a8f6e9f8893c781f9fe2c63e65b3987819576ccd2e4e1b89b13e13bb7386e6d5708ed94

data/Puppetfile

@@ -6,27 +6,27 @@ moduledir File.join(File.dirname(__FILE__), 'modules')
 
 # Core modules used by 'apply'
 mod 'puppetlabs-service', '3.1.0'
-mod 'puppet-openvox_bootstrap', '1.2.0'
+mod 'puppet-openvox_bootstrap', '1.4.0'
 mod 'puppetlabs-facts', '1.7.0'
 
 # Other core Puppet modules
-mod 'puppetlabs-inifile', '6.2.0'
-mod 'puppetlabs-apt', '11.1.0'
+mod 'puppetlabs-inifile', '6.3.1'
+mod 'puppetlabs-apt', '11.2.0'
 mod 'puppetlabs-stdlib', '9.7.0'
 mod 'puppetlabs-powershell', '6.1.0'
-mod 'puppetlabs-pwshlib', '2.0.0'
+mod 'puppetlabs-pwshlib', '2.0.1'
 
 # Core types and providers for Puppet 6
 mod 'puppetlabs-augeas_core', '2.0.1'
 mod 'puppetlabs-host_core', '2.0.1'
 mod 'puppetlabs-scheduled_task', '4.0.3'
 mod 'puppetlabs-sshkeys_core', '3.0.1'
-mod 'puppetlabs-zfs_core', '1.6.1'
+mod 'puppetlabs-zfs_core', '2.0.1'
 mod 'puppetlabs-cron_core', '2.0.2'
 mod 'puppetlabs-mount_core', '2.0.1'
 mod 'puppetlabs-selinux_core', '2.0.1'
 mod 'puppetlabs-yumrepo_core', '3.0.1'
-mod 'puppetlabs-zone_core', '2.0.1'
+mod 'puppetlabs-zone_core', '2.0.2'
 
 # Useful additional modules
 mod 'puppetlabs-package', '3.1.0'
@@ -55,4 +55,3 @@ mod 'puppetlabs-yaml', '0.2.0'
 mod 'canary', local: true
 mod 'aggregate', local: true
 mod 'puppetdb_fact', local: true
-mod 'puppet_connect', local: true

data/lib/bolt/bolt_option_parser.rb

@@ -13,6 +13,11 @@ module Bolt
                 run_context: %w[concurrency inventoryfile save-rerun cleanup puppetdb],
                 global_config_setters: PROJECT_PATHS + %w[modulepath],
                 transports: %w[transport connect-timeout tty native-ssh ssh-command copy-command],
+                choria: %w[choria-config-file choria-mcollective-certname
+                           choria-ssl-ca choria-ssl-cert choria-ssl-key
+                           choria-collective choria-puppet-environment choria-rpc-timeout
+                           choria-task-timeout choria-command-timeout choria-brokers
+                           choria-broker-timeout],
                 display: %w[format color verbose trace stream],
                 global: %w[help version log-level clear-cache] }.freeze
 
@@ -168,7 +173,7 @@ module Bolt
       when 'task'
         case action
         when 'run'
-          { flags: ACTION_OPTS + %w[params tmpdir noop],
+          { flags: ACTION_OPTS + %w[params tmpdir noop choria-task-agent],
             banner: TASK_RUN_HELP }
         when 'show'
           { flags: OPTIONS[:global] + OPTIONS[:global_config_setters] + %w[filter format],
@@ -1095,6 +1100,63 @@ module Bolt
       define('--tmpdir DIR', 'The directory to upload and execute temporary files on the target.') do |tmpdir|
         @options[:tmpdir] = tmpdir
       end
+      define('--choria-task-agent AGENT', %w[bolt_tasks shell],
+             "Which Choria agent to use for task execution (bolt_tasks, shell).",
+             "Defaults to 'bolt_tasks'. Set to 'shell' for tasks not on the Puppet Server.") do |agent|
+        @options[:'task-agent'] = agent
+      end
+      define('--choria-config-file PATH',
+             'Path to a Choria/MCollective client configuration file.') do |path|
+        @options[:'config-file'] = path
+      end
+      define('--choria-mcollective-certname NAME',
+             'Override the MCollective certname for Choria client identity.',
+             'The choria-mcorpc-support library identifies non-root clients',
+             "as '<username>.mcollective', which fails when authenticating",
+             "with a certificate that has a different CN (e.g. the host's",
+             'Puppet cert). Set this to the CN of the certificate being used.') do |name|
+        @options[:'mcollective-certname'] = name
+      end
+      define('--choria-ssl-ca PATH',
+             'CA certificate path for Choria TLS authentication.') do |path|
+        @options[:'ssl-ca'] = path
+      end
+      define('--choria-ssl-cert PATH',
+             'Client certificate path for Choria TLS authentication.') do |path|
+        @options[:'ssl-cert'] = path
+      end
+      define('--choria-ssl-key PATH',
+             'Client private key path for Choria TLS authentication.') do |path|
+        @options[:'ssl-key'] = path
+      end
+      define('--choria-collective NAME',
+             'Choria collective to route messages through.') do |name|
+        @options[:collective] = name
+      end
+      define('--choria-puppet-environment ENV',
+             "Puppet environment for bolt_tasks file downloads (default: 'production').") do |env|
+        @options[:'puppet-environment'] = env
+      end
+      define('--choria-rpc-timeout SECONDS', Integer,
+             'Seconds to wait for replies to individual Choria RPC calls (default: 30).') do |timeout|
+        @options[:'rpc-timeout'] = timeout
+      end
+      define('--choria-task-timeout SECONDS', Integer,
+             'Seconds to wait for task execution to complete (default: 300).') do |timeout|
+        @options[:'task-timeout'] = timeout
+      end
+      define('--choria-command-timeout SECONDS', Integer,
+             'Seconds to wait for commands and scripts to complete (default: 60).') do |timeout|
+        @options[:'command-timeout'] = timeout
+      end
+      define('--choria-brokers BROKERS',
+             'Choria broker addresses in host or host:port format (comma-separated). Port defaults to 4222 if omitted.') do |brokers|
+        @options[:brokers] = brokers.split(',')
+      end
+      define('--choria-broker-timeout SECONDS', Integer,
+             'Seconds to wait for the TCP connection to a Choria broker (default: 30).') do |timeout|
+        @options[:'broker-timeout'] = timeout
+      end
 
       separator "\n#{self.class.colorize(:cyan, 'Module options')}"
       define('--[no-]resolve',

data/lib/bolt/cli.rb

@@ -750,7 +750,7 @@ module Bolt
     # built-in modules are installed.
     #
     private def incomplete_install?
-      builtin_module_list = %w[aggregate canary puppetdb_fact secure_env_vars puppet_connect]
+      builtin_module_list = %w[aggregate canary puppetdb_fact secure_env_vars]
       (Dir.children(Bolt::Config::Modulepath::MODULES_PATH) - builtin_module_list).empty?
     end
 

data/lib/bolt/config/options.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative '../../bolt/config/transport/choria'
 require_relative '../../bolt/config/transport/docker'
 require_relative '../../bolt/config/transport/jail'
 require_relative '../../bolt/config/transport/local'
@@ -15,6 +16,7 @@ module Bolt
       # Transport config classes. Used to load default transport config which
       # gets passed along to the inventory.
       TRANSPORT_CONFIG = {
+        'choria' => Bolt::Config::Transport::Choria,
         'docker' => Bolt::Config::Transport::Docker,
         'jail'   => Bolt::Config::Transport::Jail,
         'local'  => Bolt::Config::Transport::Local,
@@ -76,6 +78,12 @@ module Bolt
           _example: 120,
           _plugin: true
         },
+        "headers" => {
+          description: "A map of HTTP headers to add to PuppetDB requests.",
+          type: Hash,
+          _example: { "Authorization" => "Bearer <token>" },
+          _plugin: true
+        },
         "key" => {
           description: "The private key for the certificate.",
           type: String,
@@ -545,6 +553,12 @@ module Bolt
           _example: "winrm",
           _default: "ssh"
         },
+        "choria" => {
+          description: "A map of configuration options for the choria transport.",
+          type: Hash,
+          _plugin: true,
+          _example: { "config-file" => "/etc/choria/client.conf" }
+        },
         "docker" => {
           description: "A map of configuration options for the docker transport.",
           type: Hash,

data/lib/bolt/config/transport/choria.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require_relative '../../../bolt/error'
+require_relative '../../../bolt/config/transport/base'
+
+module Bolt
+  class Config
+    module Transport
+      class Choria < Base
+        OPTIONS = %w[
+          cleanup
+          collective
+          command-timeout
+          config-file
+          host
+          interpreters
+          mcollective-certname
+          broker-timeout
+          brokers
+          puppet-environment
+          rpc-timeout
+          ssl-ca
+          ssl-cert
+          ssl-key
+          task-agent
+          task-timeout
+          tmpdir
+        ].sort.freeze
+
+        DEFAULTS = {
+          'cleanup' => true,
+          'command-timeout' => 60,
+          'broker-timeout' => 30,
+          'puppet-environment' => 'production',
+          'rpc-timeout' => 30,
+          'task-timeout' => 300,
+          'tmpdir' => '/tmp'
+        }.freeze
+
+        VALID_AGENTS = %w[bolt_tasks shell].freeze
+
+        private def validate
+          super
+
+          if @config['task-agent'] && !VALID_AGENTS.include?(@config['task-agent'])
+            raise Bolt::ValidationError,
+                  "task-agent must be one of #{VALID_AGENTS.join(', ')}, got '#{@config['task-agent']}'"
+          end
+
+          if @config['tmpdir'] && !absolute_path?(@config['tmpdir'])
+            raise Bolt::ValidationError,
+                  "Choria tmpdir must be an absolute path, got '#{@config['tmpdir']}'"
+          end
+
+          ssl_keys = %w[ssl-ca ssl-cert ssl-key]
+          provided_ssl = ssl_keys.select { |k| @config[k] }
+          if provided_ssl.any? && provided_ssl.length < ssl_keys.length
+            missing = ssl_keys - provided_ssl
+            raise Bolt::ValidationError,
+                  "When overriding Choria SSL settings, all three options must be provided " \
+                  "(ssl-ca, ssl-cert, ssl-key). Missing: #{missing.join(', ')}"
+          end
+
+          @config['interpreters'] = normalize_interpreters(@config['interpreters']) if @config['interpreters']
+        end
+
+        # Accept both POSIX absolute paths (/tmp) and Windows absolute paths (C:\temp).
+        def absolute_path?(path)
+          path.start_with?('/') || path.match?(Bolt::Transport::Choria::WINDOWS_PATH_REGEX)
+        end
+      end
+    end
+  end
+end

data/lib/bolt/config/transport/options.rb

@@ -51,6 +51,56 @@ module Bolt
             _default: true,
             _example: false
           },
+          "task-agent" => {
+            type: String,
+            description: "Which Choria agent to use for task execution. Defaults to 'bolt_tasks' " \
+                         "(downloads task files from a Puppet Server). Set to 'shell' for tasks " \
+                         "not available on the Puppet Server.",
+            _plugin: true,
+            _example: "shell"
+          },
+          "collective" => {
+            type: String,
+            description: "The Choria collective to target. Overrides the main_collective from the Choria " \
+                         "client configuration file.",
+            _plugin: true,
+            _example: "production"
+          },
+          "command-timeout" => {
+            type: Integer,
+            description: "How long to wait in seconds for commands and scripts to complete when using the " \
+                         "Choria transport.",
+            minimum: 1,
+            _plugin: true,
+            _default: 60,
+            _example: 120
+          },
+          "config-file" => {
+            type: String,
+            description: "The path to the Choria or MCollective client configuration file.",
+            _plugin: true,
+            _example: "/etc/choria/client.conf"
+          },
+          "broker-timeout" => {
+            type: Integer,
+            description: "How long to wait in seconds for the initial TCP connection to a Choria broker. " \
+                         "If the connection cannot be made within this time, the operation fails.",
+            minimum: 1,
+            _plugin: true,
+            _default: 30,
+            _example: 60
+          },
+          "rpc-timeout" => {
+            type: Integer,
+            description: "How long to wait in seconds for nodes to respond to an RPC request. " \
+                         "Used for lightweight operations like agent discovery, shell.start, and " \
+                         "shell.list polling. Distinct from command-timeout and task-timeout which " \
+                         "govern the overall duration of commands and tasks.",
+            minimum: 1,
+            _plugin: true,
+            _default: 30,
+            _example: 60
+          },
           "connect-timeout" => {
             type: Integer,
             description: "How long to wait in seconds when establishing connections. Set this value higher if you " \
@@ -225,6 +275,27 @@ module Bolt
             _plugin: true,
             _example: %w[defaults hmac-md5]
           },
+          "mcollective-certname" => {
+            type: String,
+            description: "Override the MCollective certname used for Choria client identity. " \
+                         "The choria-mcorpc-support library identifies non-root clients as " \
+                         "'<username>.mcollective'. Set this when authenticating with a certificate " \
+                         "whose CN differs from that default (e.g. the host's Puppet cert).",
+            _plugin: true,
+            _example: "primary.example.com"
+          },
+          "brokers" => {
+            type: [String, Array],
+            description: "One or more Choria broker addresses in host or host:port format. " \
+                         "Port defaults to 4222 if omitted. Do not use the nats:// prefix. " \
+                         "Overrides the middleware hosts from the Choria client configuration file. " \
+                         "Can be a single string or an array.",
+            items: {
+              type: String
+            },
+            _plugin: true,
+            _example: ["broker1:4222", "broker2:4222"]
+          },
           "native-ssh" => {
             type: [TrueClass, FalseClass],
             description: "This enables the native SSH transport, which shells out to SSH instead of using the " \
@@ -267,6 +338,14 @@ module Bolt
             _plugin: true,
             _example: "jump.example.com"
           },
+          "puppet-environment" => {
+            type: String,
+            description: "The Puppet environment to use when constructing task file URIs for the Choria " \
+                         "bolt_tasks agent.",
+            _plugin: true,
+            _default: "production",
+            _example: "staging"
+          },
           "read-timeout" => {
             type: Integer,
             description: "How long to wait in seconds when making requests to the Orchestrator.",
@@ -343,6 +422,27 @@ module Bolt
             _plugin: true,
             _example: 445
           },
+          "ssl-ca" => {
+            type: String,
+            description: "The path to the CA certificate for Choria TLS connections. Overrides the CA " \
+                         "from the Choria client configuration file.",
+            _plugin: true,
+            _example: "/etc/choria/ssl/ca.pem"
+          },
+          "ssl-cert" => {
+            type: String,
+            description: "The path to the client certificate for Choria TLS connections. Overrides the " \
+                         "certificate from the Choria client configuration file.",
+            _plugin: true,
+            _example: "/etc/choria/ssl/client.pem"
+          },
+          "ssl-key" => {
+            type: String,
+            description: "The path to the client private key for Choria TLS connections. Overrides the " \
+                         "key from the Choria client configuration file.",
+            _plugin: true,
+            _example: "/etc/choria/ssl/client-key.pem"
+          },
           "ssh-command" => {
             type: [Array, String],
             description: "The command and options to use when SSHing. This option is used when you need support for " \
@@ -393,6 +493,14 @@ module Bolt
             _default: "production",
             _example: "development"
           },
+          "task-timeout" => {
+            type: Integer,
+            description: "How long to wait in seconds for tasks to complete when using the Choria transport.",
+            minimum: 1,
+            _plugin: true,
+            _default: 300,
+            _example: 300
+          },
           "tmpdir" => {
             type: String,
             description: "The directory to upload and execute temporary files on the target.",

data/lib/bolt/executor.rb

@@ -13,6 +13,7 @@ require_relative '../bolt/puppetdb'
 require_relative '../bolt/result'
 require_relative '../bolt/result_set'
 # Load transports
+require_relative '../bolt/transport/choria'
 require_relative '../bolt/transport/docker'
 require_relative '../bolt/transport/jail'
 require_relative '../bolt/transport/local'
@@ -24,6 +25,7 @@ require_relative '../bolt/transport/winrm'
 
 module Bolt
   TRANSPORTS = {
+    choria: Bolt::Transport::Choria,
     docker: Bolt::Transport::Docker,
     jail: Bolt::Transport::Jail,
     local: Bolt::Transport::Local,

data/lib/bolt/pal/yaml_plan/transpiler.rb

@@ -22,7 +22,7 @@ module Bolt
 
           plan_object = parse_plan
           param_descriptions = plan_object.parameters.map do |param|
-            str = String.new("# @param #{param.name}")
+            str = "# @param #{param.name}"
             str << " #{param.description}" if param.description
             str
           end.join("\n")

data/lib/bolt/plugin/puppetdb.rb

@@ -5,7 +5,7 @@ module Bolt
     class Puppetdb
       class FactLookupError < Bolt::Error
         def initialize(fact, err = nil)
-          m = String.new("Fact lookup '#{fact}' contains an invalid factname")
+          m = "Fact lookup '#{fact}' contains an invalid factname"
           m << ": #{err}" unless err.nil?
           super(m, 'bolt.plugin/fact-lookup-error')
         end

data/lib/bolt/plugin.rb

@@ -127,7 +127,7 @@ module Bolt
       end
     end
 
-    RUBY_PLUGINS = %w[task prompt env_var puppetdb puppet_connect_data].freeze
+    RUBY_PLUGINS = %w[task prompt env_var puppetdb].freeze
     BUILTIN_PLUGINS = %w[task terraform pkcs7 prompt vault aws_inventory puppetdb azure_inventory
                          yaml env_var gcloud_inventory].freeze
     DEFAULT_PLUGIN_HOOKS = { 'puppet_library' => { 'plugin' => 'openvox_bootstrap', 'stop_service' => true } }.freeze
@@ -255,9 +255,6 @@ module Bolt
       hooks = KNOWN_HOOKS.map { |hook| [hook, {}] }.to_h
 
       @plugins.sort.each do |name, plugin|
-        # Don't show the Puppet Connect plugin for now.
-        next if name == 'puppet_connect_data'
-
         case plugin
         when Bolt::Plugin::Module
           plugin.hook_map.each do |hook, spec|

data/lib/bolt/puppetdb/config.rb

@@ -149,6 +149,14 @@ module Bolt
         @settings['key']
       end
 
+      def headers
+        if @settings['headers'] && !@settings['headers'].is_a?(Hash)
+          raise Bolt::PuppetDBError, "headers must be a Hash"
+        end
+
+        @settings['headers']
+      end
+
       def validate_cert_and_key
         if (@settings['cert'] && !@settings['key']) ||
            (!@settings['cert'] && @settings['key'])

data/lib/bolt/puppetdb/instance.rb

@@ -139,6 +139,7 @@ module Bolt
 
       def headers
         headers = { 'Content-Type' => 'application/json' }
+        headers.merge!(@config.headers) if @config.headers
         headers['X-Authentication'] = @config.token if @config.token
         headers
       end

data/lib/bolt/result_set.rb

@@ -27,7 +27,7 @@ module Bolt
 
     def iterator
       if Object.const_defined?(:Puppet) && Puppet.const_defined?(:Pops) &&
-         self.class.included_modules.include?(Puppet::Pops::Types::Iterable)
+         self.class.include?(Puppet::Pops::Types::Iterable)
         Puppet::Pops::Types::Iterable.on(@results, Bolt::Result)
       else
         raise NotImplementedError, "iterator requires puppet code to be loaded."

data/lib/bolt/transport/choria/agent_discovery.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+module Bolt
+  module Transport
+    class Choria
+      SHELL_MIN_VERSION = '1.2.1'
+
+      AGENT_MIN_VERSIONS = {
+        'shell' => SHELL_MIN_VERSION
+      }.freeze
+
+      # Discover agents and detect OS on targets via two batched RPC calls
+      # (agent_inventory for agents+versions, get_fact for os.family).
+      # Populates @agent_cache with { agents: [...], os: 'redhat' | 'windows' | ... }.
+      #
+      # @param targets [Array<Bolt::Target>] Targets to discover agents on
+      def discover_agents(targets)
+        uncached = targets.reject { |target| @agent_cache.key?(choria_identity(target)) }
+        return if uncached.empty?
+
+        logger.debug { "Discovering agents on #{target_count(uncached)}" }
+        discover_agent_list(uncached)
+        discover_os_family(uncached)
+
+        uncached.each do |target|
+          identity = choria_identity(target)
+          logger.warn { "No response from #{identity} during agent discovery" } unless @agent_cache.key?(identity)
+        end
+      end
+
+      def has_agent?(target, agent_name)
+        @agent_cache[choria_identity(target)]&.dig(:agents)&.include?(agent_name) || false
+      end
+
+      def windows_target?(target)
+        @agent_cache[choria_identity(target)]&.dig(:os) == 'windows'
+      end
+
+      # Discover available agents on targets via rpcutil.agent_inventory
+      # and populate @agent_cache with agent lists.
+      #
+      # @param targets [Array<Bolt::Target>] Targets to query for agent inventory
+      def discover_agent_list(targets)
+        response = rpc_request('rpcutil', targets, 'rpcutil.agent_inventory') do |client|
+          client.agent_inventory
+        end
+        response[:errors].each { |target, output| logger.debug { "agent_inventory failed for #{target.safe_name}: #{output[:error]}" } }
+
+        response[:responded].each do |target, data|
+          sender = choria_identity(target)
+          agents = filter_agents(sender, data[:agents])
+          unless agents
+            logger.warn { "Unexpected agent_inventory response from #{sender}. This target will be treated as unreachable." }
+            next
+          end
+          @agent_cache[sender] = { agents: agents }
+          logger.debug { "Discovered agents on #{sender}: #{agents.join(', ')}" }
+        end
+      rescue StandardError => e
+        raise if e.is_a?(Bolt::Error)
+
+        logger.warn { "Agent discovery failed: #{e.class}: #{e.message}" }
+      end
+
+      # Detect the OS family on targets via rpcutil.get_fact and update
+      # @agent_cache entries with the :os key.
+      #
+      # @param targets [Array<Bolt::Target>] Targets to detect OS on
+      def discover_os_family(targets)
+        # Only fetch OS for targets that responded to agent_inventory
+        responded = targets.select { |target| @agent_cache.key?(choria_identity(target)) }
+        return if responded.empty?
+
+        response = rpc_request('rpcutil', responded, 'rpcutil.get_fact') do |client|
+          client.get_fact(fact: 'os.family')
+        end
+        response[:errors].each { |target, output|
+          logger.warn {
+            "OS detection failed for #{target.safe_name}: #{output[:error]}. Defaulting to POSIX command syntax."
+          }
+        }
+
+        response[:responded].each do |target, data|
+          sender = choria_identity(target)
+          os_family = data[:value].to_s.downcase
+          if os_family.empty?
+            logger.warn { "os.family fact is empty on #{sender}. Defaulting to POSIX command syntax." }
+            next
+          end
+          @agent_cache[sender][:os] = os_family
+          logger.debug { "Detected OS on #{sender}: #{os_family}" }
+        end
+      rescue StandardError => e
+        raise if e.is_a?(Bolt::Error)
+
+        logger.warn { "OS detection failed: #{e.class}: #{e.message}. Defaulting to POSIX command syntax." }
+      end
+
+      # Filter out agents that don't meet minimum version requirements.
+      #
+      # @param sender [String] Choria node identity (for logging)
+      # @param agent_list [Array<Hash>, nil] Agent entries from agent_inventory, each with
+      #   :agent (name) and :version keys
+      # @return [Array<String>, nil] Agent names that meet version requirements, or nil
+      #   if agent_list is not an Array
+      def filter_agents(sender, agent_list)
+        return nil unless agent_list.is_a?(Array)
+
+        agent_list.filter_map do |entry|
+          name = entry['agent']
+          next unless name
+
+          version = entry['version']
+          min_version = AGENT_MIN_VERSIONS[name]
+          if min_version && !meets_min_version?(version, min_version)
+            logger.warn {
+              "The '#{name}' agent on #{sender} is version #{version || 'unknown'}, " \
+              "but #{min_version} or later is required. It will be treated as unavailable."
+            }
+            next
+          end
+
+          name
+        end
+      end
+
+      def meets_min_version?(version, min_version)
+        return false unless version
+
+        Gem::Version.new(version) >= Gem::Version.new(min_version)
+      rescue ArgumentError => e
+        logger.warn { "Could not parse version '#{version}': #{e.message}. Treating agent as unavailable." }
+        false
+      end
+    end
+  end
+end