swarm_cli 2.1.12 → 3.0.0.alpha2

data/lib/swarm_cli/v3/cli.rb

@@ -0,0 +1,721 @@
+# frozen_string_literal: true
+
+module SwarmCLI
+  module V3
+    # Entry point for the V3 agent chat CLI.
+    #
+    # Supports three run modes:
+    # - **Interactive**: REPL with always-available input, history
+    # - **Prompt**: Run a single prompt and exit (non-interactive)
+    # - **Maintenance**: Run memory defrag and exit
+    #
+    # @example
+    #   SwarmCLI::V3::CLI.start(ARGV)
+    class CLI
+      HISTORY_FILE = File.expand_path(ENV.fetch("SWARM_V3_HISTORY", "~/.swarm/v3_history"))
+      HISTORY_SIZE = 1000
+      CONFIG_FILE = File.expand_path("~/.config/swarm/cli.json")
+
+      class << self
+        # Parse arguments and run the appropriate mode.
+        #
+        # @param argv [Array<String>] command-line arguments
+        # @return [void]
+        def start(argv)
+          new(argv).run
+        end
+      end
+
+      # @param argv [Array<String>] command-line arguments
+      def initialize(argv)
+        @original_argv = strip_reboot_flag(argv.dup).freeze
+        @argv = argv.dup
+        @options = {}
+      end
+
+      # Parse arguments, load agent, and dispatch to the appropriate mode.
+      #
+      # @return [void]
+      def run
+        parse_options!
+        configure_providers!
+        agent = load_agent(@argv.first)
+        register_reboot_tool!
+
+        handle_reboot_continuation(agent) if @options[:reboot_from]
+
+        if @options[:defrag]
+          run_maintenance(agent)
+        elsif @options[:prompt] && !@options[:reboot_from]
+          run_prompt(agent)
+        else
+          run_interactive(agent)
+        end
+      end
+
+      # Expand @file mentions to include file contents.
+      # This is a public utility method that can be used for testing.
+      #
+      # @param prompt [String] the prompt text with @file mentions
+      # @param display [Display, nil] optional display to show read status
+      # @return [String] the expanded prompt with file contents
+      def expand_file_mentions(prompt, display: nil)
+        prompt.gsub(%r{@([\w/.~-]+)}) do |match|
+          path = Regexp.last_match(1)
+
+          if File.file?(path)
+            content = File.read(path, encoding: "UTF-8")
+            display&.agent_print(ANSIColors.dim("  \u{1F4C4} Read @#{path}"))
+            "\n\n<file path=\"#{path}\">\n#{content}\n</file>\n"
+          elsif File.directory?(path)
+            entries = Dir.children(path).sort
+            display&.agent_print(ANSIColors.dim("  \u{1F4C2} Read @#{path}/ (#{entries.size} entries)"))
+            "\n\n<directory path=\"#{path}\">\n#{entries.join("\n")}\n</directory>\n"
+          else
+            match # Keep original if path doesn't exist
+          end
+        rescue StandardError => _e
+          match # Keep original on error
+        end
+      end
+
+      private
+
+      # ----------------------------------------------------------------
+      # Argument parsing
+      # ----------------------------------------------------------------
+
+      def parse_options!
+        parser = OptionParser.new do |opts|
+          opts.banner = "Usage: swarm3 <agent_definition.rb> [options]"
+
+          opts.on("-p", "--prompt PROMPT", "Run a single prompt and exit") do |p|
+            @options[:prompt] = p
+          end
+
+          opts.on("--defrag", "Run memory maintenance and exit") do
+            @options[:defrag] = true
+          end
+
+          opts.on("--reboot-from PID", Integer, "Internal: consume reboot signal") do |pid|
+            @options[:reboot_from] = pid
+          end
+
+          opts.on("-h", "--help", "Show this help") do
+            puts opts
+            exit
+          end
+        end
+
+        parser.parse!(@argv)
+
+        return unless @argv.empty?
+
+        warn(parser.banner)
+        warn("Example: swarm3 experiments/v3/agents/example.rb")
+        warn("         swarm3 experiments/v3/agents/example.rb -p \"Hello\"")
+        warn("         swarm3 experiments/v3/agents/example.rb --defrag")
+        exit(1)
+      end
+
+      def strip_reboot_flag(args)
+        if (idx = args.index("--reboot-from"))
+          args.slice!(idx, 2)
+        end
+        args
+      end
+
+      # ----------------------------------------------------------------
+      # Configuration & loading
+      # ----------------------------------------------------------------
+
+      def configure_providers!
+        SwarmSDK::V3.configure do |config|
+          config.anthropic_api_key = ENV["ANTHROPIC_API_KEY"] if ENV["ANTHROPIC_API_KEY"]
+          config.openai_api_key = ENV["OPENAI_API_KEY"] if ENV["OPENAI_API_KEY"]
+          config.gemini_api_key = ENV["GEMINI_API_KEY"] if ENV["GEMINI_API_KEY"]
+        end
+      end
+
+      def load_agent(path)
+        unless path && File.exist?(path)
+          warn("File not found: #{path}")
+          exit(1)
+        end
+
+        agent = eval(File.read(path), binding, path) # rubocop:disable Security/Eval
+        unless agent.is_a?(SwarmSDK::V3::Agent)
+          warn("File must return a SwarmSDK::V3::Agent (got #{agent.class})")
+          exit(1)
+        end
+
+        agent
+      end
+
+      def register_reboot_tool!
+        SwarmSDK::V3::Tools::Registry.register(:Reboot, RebootTool)
+        RebootTool.session_pid = Process.pid
+      end
+
+      # ----------------------------------------------------------------
+      # Non-interactive mode
+      # ----------------------------------------------------------------
+
+      def run_prompt(agent)
+        expanded_prompt = expand_file_mentions(@options[:prompt])
+        ask_with_display(agent, expanded_prompt)
+        check_and_reboot!(agent)
+      end
+
+      def ask_with_display(agent, prompt)
+        full_content = +""
+
+        agent.ask(prompt) do |event|
+          case event[:type]
+          when "content_chunk"
+            full_content << event[:content] if event[:content]
+          else
+            line = EventRenderer.format(event)
+            puts line if line
+          end
+        end
+
+        return if full_content.empty?
+
+        puts
+        puts ANSIColors.cyan("#{agent.name}> ")
+        puts TTY::Markdown.parse(full_content)
+      end
+
+      # ----------------------------------------------------------------
+      # Maintenance mode
+      # ----------------------------------------------------------------
+
+      def run_maintenance(agent, printer: method(:puts))
+        unless agent.definition.memory_enabled?
+          printer.call(ANSIColors.yellow("Memory not enabled for this agent."))
+          return
+        end
+
+        printer.call(ANSIColors.cyan("--- Running Maintenance ---"))
+        result = agent.defrag!
+        format_maintenance_result(result, agent.memory.stats).each { |line| printer.call(line) }
+        printer.call(ANSIColors.cyan("---------------------------"))
+      end
+
+      # Format defrag results and memory stats into display lines.
+      #
+      # @param result [Hash] defrag result
+      # @param stats [Hash] memory stats
+      # @return [Array<String>] formatted lines
+      def format_maintenance_result(result, stats)
+        lines = [
+          "  #{ANSIColors.bold("Duplicates merged:")}  #{result[:duplicates_merged]}",
+          "  #{ANSIColors.bold("Conflicts detected:")} #{result[:conflicts_detected]}",
+          "  #{ANSIColors.bold("Cards compressed:")}   #{result[:cards_compressed]}",
+          "  #{ANSIColors.bold("Cards promoted:")}     #{result[:cards_promoted]}",
+          "  #{ANSIColors.bold("Cards pruned:")}       #{result[:cards_pruned]}",
+          "",
+          ANSIColors.dim("Cards: #{stats[:total_cards]}, Clusters: #{stats[:total_clusters]}"),
+        ]
+
+        if stats[:compression_levels].any?
+          levels = stats[:compression_levels].sort.map { |lvl, cnt| "L#{lvl}=#{cnt}" }.join(", ")
+          lines << ANSIColors.dim("Compression levels: #{levels}")
+        end
+
+        if stats[:card_types].any?
+          types = stats[:card_types].sort_by { |_, cnt| -cnt }.map { |type, cnt| "#{type}=#{cnt}" }.join(", ")
+          lines << ANSIColors.dim("Card types: #{types}")
+        end
+
+        lines
+      end
+
+      # ----------------------------------------------------------------
+      # Reboot support
+      # ----------------------------------------------------------------
+
+      def handle_reboot_continuation(agent)
+        signal = RebootTool.consume_signal(agent.definition.directory, @options[:reboot_from])
+        return unless signal
+
+        puts ANSIColors.cyan("\u{1F504} [Reboot] Continuing after reboot...")
+        puts ANSIColors.dim("Reason: #{signal[:reason]}") if signal[:reason]
+        puts
+
+        ask_with_display(agent, signal[:continuation_message])
+        check_and_reboot!(agent)
+
+        exit(0) if @options[:prompt] || @options[:defrag]
+      end
+
+      def check_and_reboot!(agent)
+        return unless RebootTool.signal_pending?(agent.definition.directory, Process.pid)
+
+        puts ANSIColors.yellow("\n\u{1F504} [Reboot] Restarting process to reload changes...")
+        exec(RbConfig.ruby, File.expand_path($PROGRAM_NAME), *@original_argv, "--reboot-from", Process.pid.to_s)
+      end
+
+      # ----------------------------------------------------------------
+      # Interactive mode
+      # ----------------------------------------------------------------
+
+      def run_interactive(agent)
+        print_banner(agent)
+
+        display = Display.new
+        reader = RawInputReader.new(display)
+        reader.load_history_file(HISTORY_FILE)
+        emitter = build_sync_emitter(agent, display)
+        @follow_up_queue = []
+        @defrag_queue = []
+        @defrag_active = false
+        @autocomplete_state = nil # [pre, target, post] when autocomplete is active
+        @autocomplete_mode = :manual # :manual (Tab-triggered) or :auto (as-you-type)
+        load_settings # Load saved settings from config file
+
+        reader.start
+
+        begin
+          Async do |reactor|
+            SwarmSDK::V3::EventStream.emitter = emitter
+            display.activate
+            interactive_loop(reactor, agent, display, reader)
+          end
+        ensure
+          display.deactivate
+          reader.stop
+          reader.save_history_file(HISTORY_FILE)
+        end
+      end
+
+      def print_banner(agent)
+        puts ANSIColors.bold("\u{1F41D} V3 Agent Chat")
+        puts ANSIColors.dim("\u{1F916} Agent: #{agent.name} | Model: #{agent.definition.model}")
+        mem_status = agent.definition.memory_enabled? ? "\u{1F4C1} #{agent.definition.memory_directory}" : "\u{274C} disabled"
+        puts ANSIColors.dim("\u{1F9E0} Memory: #{mem_status}")
+        puts ANSIColors.dim("Option+Enter for newline. Ctrl-C interrupts agent, double Ctrl-C quits.")
+        puts ANSIColors.dim("Type while agent is working to steer. /queue <prompt> for follow-up tasks.")
+        puts ANSIColors.dim("Commands: /clear /memory /defrag /queue /reboot /exit")
+        puts
+      end
+
+      def build_sync_emitter(agent, display)
+        lambda { |event|
+          activity = EventRenderer.format_activity(event)
+          if activity
+            display.update_activity(activity)
+          else
+            line = EventRenderer.format(event)
+            display.agent_print(line) if line
+          end
+        }
+      end
+
+      def interactive_loop(reactor, agent, display, reader)
+        agent_active = false
+
+        loop do
+          event = reader.next_event
+
+          case event
+          in [:dropdown_enter]
+            # Enter pressed with dropdown open: accept selection without submitting
+            handle_dropdown_enter_accept(display)
+          in [:line, line]
+            line = line.strip
+            next if line.empty?
+
+            # Handle slash commands - may return true, false, [:process, prompt], or [:defrag]
+            cmd_result = handle_slash_command(line, agent, display, reader, agent_active || @defrag_active)
+            case cmd_result
+            when true
+              next
+            when [:defrag]
+              # Run defrag asynchronously
+              @defrag_active = true
+              reactor.async do
+                run_defrag_with_progress(agent, display)
+              rescue StandardError => e
+                display.agent_print(ANSIColors.red("Defrag error: #{e.class}: #{e.message}"))
+              ensure
+                @defrag_active = false
+              end
+              next
+            when Array
+              # [:process, prompt] - command wants us to process this prompt
+              line = cmd_result[1]
+            end
+
+            # Queue input during defrag
+            if @defrag_active
+              @defrag_queue << line
+              display.agent_print(ANSIColors.cyan("  \u{1F4CB} Queued for after defrag: #{EventRenderer.truncate(line, 60)}"))
+              next
+            end
+
+            if agent.running? || agent_active
+              agent.steer(line)
+              display.agent_print(ANSIColors.yellow("  \u{1F3AF} Steering: #{EventRenderer.truncate(line, 80)}"))
+            else
+              agent_active = true
+              reactor.async do
+                ask_with_display_sync(agent, line, display)
+
+                # Process queued follow-ups one at a time
+                while (follow_up = @follow_up_queue.shift)
+                  display.agent_print(ANSIColors.cyan("  \u{1F4CB} Processing queued: #{EventRenderer.truncate(follow_up, 60)}"))
+                  ask_with_display_sync(agent, follow_up, display)
+                end
+
+                check_and_reboot_sync!(agent, display, reader)
+              rescue StandardError => e
+                display.agent_print(ANSIColors.red("Error: #{e.class}: #{e.message}"))
+              ensure
+                agent_active = false
+              end
+            end
+          in [:interrupt]
+            if agent.running? || agent_active
+              agent.interrupt!
+              display.agent_print(ANSIColors.dim("(interrupted)"))
+            end
+            # Hint is now shown in the status area below the input
+          in [:tab]
+            # Tab triggers autocomplete (navigation handled in RawInputReader)
+            handle_autocomplete_trigger(agent, display)
+          in [:toggle_autocomplete]
+            # Toggle between auto and manual autocomplete modes
+            @autocomplete_mode = @autocomplete_mode == :auto ? :manual : :auto
+            mode_name = @autocomplete_mode == :auto ? "auto" : "manual"
+            display.clear_hint # Clear any existing hint first
+            display.show_hint("Autocomplete: #{mode_name}", duration: 2.0)
+            save_settings # Persist to config file
+          in [:char_typed, _char]
+            # Auto-trigger autocomplete if in auto mode
+            if @autocomplete_mode == :auto
+              handle_autocomplete_trigger(agent, display)
+            elsif display.dropdown_active?
+              # Manual mode: close dropdown on typing
+              display.dropdown_close
+            end
+          in [:eof] | [:exit]
+            display.agent_print(ANSIColors.dim("Goodbye!"))
+            break
+          end
+        end
+      end
+
+      # Trigger autocomplete: extract word, find matches, show dropdown
+      def handle_autocomplete_trigger(agent, display)
+        buffer = display.current_buffer
+        cursor = display.text_input.cursor
+
+        # Check if this is a command (starts with /)
+        if buffer.start_with?("/")
+          result = CommandCompleter.extract_command_word(buffer, cursor)
+          return unless result
+
+          pre, target, post = result
+
+          # Only show dropdown if user typed at least one character after /
+          return if target.length < 2 # Need at least "/x"
+
+          # Include available skills in autocomplete
+          skill_names = available_skill_names(agent)
+          matches = CommandCompleter.find_matches(target, max: 5, skills: skill_names)
+
+        else
+          # File autocomplete (with @)
+          result = FileCompleter.extract_completion_word(buffer, cursor)
+          return unless result # No @ prefix found
+
+          pre, target, post = result
+
+          # Only show dropdown if user typed at least one character after @
+          return if target.length < 2 # Need at least "@x"
+
+          matches = FileCompleter.find_matches(target, max: 5)
+
+        end
+        return if matches.empty?
+
+        dropdown = Dropdown.new(items: matches, max_visible: 5)
+        display.show_dropdown(dropdown)
+        @autocomplete_state = [pre, target, post]
+      end
+
+      # Handle Enter when dropdown is open: select current + add space
+      def handle_dropdown_enter_accept(display)
+        selected = display.dropdown_accept
+        return unless selected && @autocomplete_state
+
+        pre, _target, post = @autocomplete_state
+        new_buffer = "#{pre}#{selected} #{post}" # Add space after selection
+        display.replace_buffer(new_buffer)
+        @autocomplete_state = nil
+      end
+
+      def ask_with_display_sync(agent, prompt, display)
+        # Expand file mentions before sending to agent (shows read status)
+        expanded_prompt = expand_file_mentions(prompt, display: display)
+
+        display.start_working
+        full_content = +""
+        input_tokens = expanded_prompt.length / 4
+        output_chars = 0
+
+        begin
+          # Only handle content_chunk in the block for content accumulation.
+          # Other events flow through the global emitter (build_sync_emitter)
+          # to avoid double-rendering.
+          agent.ask(expanded_prompt) do |event|
+            next unless event[:type] == "content_chunk" && event[:content]
+
+            full_content << event[:content]
+            output_chars += event[:content].length
+            display.update_activity("\u{2193} ~#{input_tokens + (output_chars / 4)} tokens")
+          end
+        ensure
+          display.stop_working
+        end
+
+        return if full_content.empty?
+
+        rendered = TTY::Markdown.parse(full_content)
+        display.agent_print("\n#{ANSIColors.cyan("#{agent.name}> ")}\n#{rendered}")
+      end
+
+      # Run defrag with progress display and handle queued input after completion.
+      #
+      # @param agent [SwarmSDK::V3::Agent] the agent
+      # @param display [Display] the display coordinator
+      # @return [void]
+      def run_defrag_with_progress(agent, display)
+        unless agent.definition.memory_enabled?
+          display.agent_print(ANSIColors.yellow("Memory not enabled for this agent."))
+          return
+        end
+
+        display.start_working
+
+        begin
+          result = agent.defrag! do |event|
+            case event[:type]
+            when "memory_defrag_progress"
+              activity = EventRenderer.format_defrag_progress(event)
+              display.update_activity(activity) if activity
+            when "memory_defrag_start", "memory_defrag_complete"
+              line = EventRenderer.format(event)
+              display.agent_print(line) if line
+            when /^memory_.*_error$/
+              # Display memory error events (compression_batch_error, promotion_llm_error, etc.)
+              display.agent_print(ANSIColors.red("  \u{26A0}\u{FE0F} #{event[:type]}: #{event[:error]}"))
+            end
+          end
+          format_maintenance_result(result, agent.memory.stats).each { |line| display.agent_print(line) }
+        ensure
+          display.stop_working
+        end
+
+        # Process queued messages after defrag (merged into single prompt)
+        process_defrag_queue(agent, display) if @defrag_queue.any?
+      end
+
+      # Process messages queued during defrag by merging them into a single prompt.
+      #
+      # @param agent [SwarmSDK::V3::Agent] the agent
+      # @param display [Display] the display coordinator
+      # @return [void]
+      def process_defrag_queue(agent, display)
+        return if @defrag_queue.empty?
+
+        messages = @defrag_queue.dup
+        @defrag_queue.clear
+
+        merged_prompt = messages.join("\n\n")
+        display.agent_print(ANSIColors.cyan("  \u{1F4CB} Processing #{messages.size} queued message#{"s" if messages.size != 1}..."))
+
+        ask_with_display_sync(agent, merged_prompt, display)
+      end
+
+      # ----------------------------------------------------------------
+      # Slash commands (interactive mode)
+      # ----------------------------------------------------------------
+
+      def handle_slash_command(input, agent, display, reader, agent_active = false)
+        case input
+        when "/clear"
+          agent.clear
+          @follow_up_queue&.clear
+          display.agent_print(ANSIColors.yellow("Conversation and queue cleared (memory preserved)."))
+          true
+        when "/memory"
+          show_memory_stats_sync(agent, display)
+          true
+        when "/defrag"
+          # Return special marker to run defrag asynchronously
+          [:defrag]
+        when "/reboot"
+          display.deactivate
+          reader.stop
+          reader.save_history_file(HISTORY_FILE)
+          puts ANSIColors.yellow("\u{1F504} Rebooting to reload code changes...")
+          exec(RbConfig.ruby, File.expand_path($PROGRAM_NAME), *@original_argv)
+        when "/exit", "/quit"
+          display.agent_print(ANSIColors.dim("Goodbye!"))
+          display.deactivate
+          reader.stop
+          reader.save_history_file(HISTORY_FILE)
+          exit(0)
+        when %r{^/queue\s+(.+)}i
+          prompt = Regexp.last_match(1).strip
+          if agent.running? || agent_active
+            # Agent is busy - queue for later
+            @follow_up_queue << prompt
+            display.agent_print(ANSIColors.cyan("  \u{1F4CB} Queued: #{EventRenderer.truncate(prompt, 80)}"))
+            true
+          else
+            # Agent is idle - process immediately
+            [:process, prompt]
+          end
+        when "/queue"
+          display.agent_print(ANSIColors.red("Usage: /queue <prompt>"))
+          true
+        when %r{^/([a-zA-Z0-9_-]+)(?:\s+(.+))?}
+          # Check if this is a skill invocation (supports hyphens in names)
+          skill_name = Regexp.last_match(1)
+          user_prompt = Regexp.last_match(2) || ""
+
+          # Try to find matching skill
+          skill = find_skill(agent, skill_name)
+          if skill
+            # Read skill file and combine with user prompt
+            skill_content = File.read(skill.location, encoding: "UTF-8")
+            combined_prompt = "#{skill_content}\n\n#{user_prompt}".strip
+            display.agent_print(ANSIColors.dim("  \u{1F4DA} Skill: /#{skill.name}"))
+            [:process, combined_prompt]
+          else
+            # Unknown command
+            display.agent_print(ANSIColors.red("Unknown command: #{input}"))
+            display.agent_print(ANSIColors.dim("Commands: /clear /memory /defrag /queue /reboot /exit"))
+            true
+          end
+        else
+          false
+        end
+      end
+
+      def show_memory_stats_sync(agent, display)
+        unless agent.definition.memory_enabled?
+          display.agent_print(ANSIColors.yellow("Memory not enabled for this agent."))
+          return
+        end
+
+        tokens = agent.tokens
+        lines = [
+          ANSIColors.cyan("--- Memory Stats ---"),
+          "  Messages:      #{agent.messages.size}",
+          "  Input tokens:  #{tokens[:input]}",
+          "  Output tokens: #{tokens[:output]}",
+        ]
+
+        # Memory store is lazily initialized on first ask()
+        if agent.memory
+          cards = agent.memory.adapter.list_cards
+          lines.insert(1, "  Cards:         #{cards.size}")
+        else
+          lines.insert(1, "  Cards:         (not loaded yet)")
+        end
+
+        lines << ANSIColors.cyan("--------------------")
+        display.agent_print(lines.join("\n"))
+      end
+
+      # ----------------------------------------------------------------
+      # Interactive reboot
+      # ----------------------------------------------------------------
+
+      def check_and_reboot_sync!(agent, display, reader)
+        return unless RebootTool.signal_pending?(agent.definition.directory, Process.pid)
+
+        display.deactivate
+        reader.stop
+        reader.save_history_file(HISTORY_FILE)
+        puts ANSIColors.yellow("\n\u{1F504} [Reboot] Restarting process to reload changes...")
+        exec(
+          RbConfig.ruby,
+          File.expand_path($PROGRAM_NAME),
+          *@original_argv,
+          "--reboot-from",
+          Process.pid.to_s,
+        )
+      end
+
+      # Load CLI settings from config file
+      def load_settings
+        # Ensure config directory exists on startup
+        FileUtils.mkdir_p(File.dirname(CONFIG_FILE))
+
+        return unless File.exist?(CONFIG_FILE)
+
+        data = JSON.parse(File.read(CONFIG_FILE))
+        @autocomplete_mode = data["autocomplete_mode"]&.to_sym || :manual
+      rescue StandardError => _e
+        @autocomplete_mode = :manual
+      end
+
+      # Save CLI settings to config file
+      def save_settings
+        FileUtils.mkdir_p(File.dirname(CONFIG_FILE))
+        data = {
+          "autocomplete_mode" => @autocomplete_mode.to_s,
+        }
+        File.write(CONFIG_FILE, JSON.pretty_generate(data))
+      rescue StandardError => _e
+        # Silently ignore save errors
+        nil
+      end
+
+      # Get list of available skill names for autocomplete
+      #
+      # @param agent [SwarmSDK::V3::Agent] the agent
+      # @return [Array<String>] array of skill names
+      def available_skill_names(agent)
+        # If agent has loaded skills, use them
+        if agent.loaded_skills
+          return agent.loaded_skills.map(&:name)
+        end
+
+        # Otherwise, scan skill directories directly
+        return [] if agent.definition.skills.empty?
+
+        manifests = SwarmSDK::V3::Skills::Loader.scan(agent.definition.skills)
+        manifests.map(&:name)
+      rescue StandardError => _e
+        []
+      end
+
+      # Find a skill by name from the agent's loaded skills
+      #
+      # @param agent [SwarmSDK::V3::Agent] the agent
+      # @param name [String] the skill name to find
+      # @return [SwarmSDK::V3::Skills::Manifest, nil] the skill manifest or nil
+      def find_skill(agent, name)
+        # If agent has loaded skills, search them
+        if agent.loaded_skills
+          return agent.loaded_skills.find { |s| s.name.downcase == name.downcase }
+        end
+
+        # Otherwise, scan skill directories directly
+        return if agent.definition.skills.empty?
+
+        manifests = SwarmSDK::V3::Skills::Loader.scan(agent.definition.skills)
+        manifests.find { |s| s.name.downcase == name.downcase }
+      rescue StandardError => _e
+        nil
+      end
+    end
+  end
+end