swarm_sdk 2.7.13 → 3.0.0.alpha1

data/lib/swarm_sdk/v3/sub_task_agent.rb

@@ -0,0 +1,248 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module V3
+    # Ephemeral agent for focused subtask execution
+    #
+    # SubTaskAgent is a lightweight copy of an Agent that shares the parent's
+    # memory store in read-only mode. It inherits all of the parent's
+    # capabilities (MCP connections, skills, tools) but skips memory writes,
+    # STM capture, ingestion, and eviction.
+    #
+    # ## Design
+    #
+    # Rather than adding flags to Agent, SubTaskAgent overrides the specific
+    # lifecycle methods that differ. This keeps Agent unchanged (zero regression
+    # risk) and encapsulates all subtask behavior in one class.
+    #
+    # ## What's inherited unchanged from Agent
+    #
+    # - {#connect_mcp_servers} — full MCP connections
+    # - {#load_skills} — same skill directories
+    # - {#create_chat} / {#configure_chat} — fresh chat, same model/params
+    # - {#build_base_system_prompt} — same system prompt + skills metadata
+    # - {#ask} / {#execute_turn} — same turn flow (memory writes are no-ops)
+    # - {#interrupt!} — interruption safety preserved
+    # - {#clear} — proper MCP cleanup
+    #
+    # ## What's overridden
+    #
+    # - {#initialize_memory} — uses parent's memory store instead of creating one
+    # - {#capture_turn} — no-op (subtask is ephemeral)
+    # - {#ingest_into_memory} — no-op (read-only memory)
+    # - {#evict_stm} — no-op (no STM to evict)
+    # - {#memory_read_only?} — returns true (skips access counter updates)
+    # - {#attach_tools} — passes subtask_depth to Registry
+    #
+    # @example
+    #   subtask = SubTaskAgent.new(
+    #     definition,
+    #     parent_memory_store: agent.memory,
+    #     subtask_depth: 1,
+    #   )
+    #   response = subtask.ask("Analyze the auth module")
+    #   subtask.clear  # disconnects MCP
+    class SubTaskAgent < Agent
+      # @return [Integer] Current subtask nesting depth
+      attr_reader :subtask_depth
+
+      # Create a new subtask agent
+      #
+      # @param definition [AgentDefinition] Agent configuration (same as parent)
+      # @param parent_memory_store [Memory::Store, nil] Parent's memory store (read-only)
+      # @param subtask_depth [Integer] Current nesting depth
+      def initialize(definition, parent_memory_store:, subtask_depth:)
+        super(definition)
+        @parent_memory_store = parent_memory_store
+        @subtask_depth = subtask_depth
+      end
+
+      # Whether this agent is running as a subtask
+      #
+      # @return [Boolean] Always true for SubTaskAgent
+      def subtask_mode?
+        true
+      end
+
+      # Whether memory operations are read-only
+      #
+      # @return [Boolean] Always true — subtasks don't update access counters
+      def memory_read_only?
+        true
+      end
+
+      # Resolve subtask model configuration with fallback chain
+      #
+      # Resolution order:
+      # 1. Agent-level subtask config (definition.subtask_*)
+      # 2. Global config subtask config (Configuration.subtask_*)
+      # 3. Parent's model config (fallback)
+      #
+      # @return [Hash] Configuration hash with :model, :provider, :base_url, :headers, :parameters
+      #
+      # @example Check what model a subtask will use
+      #   subtask_agent.resolved_subtask_config[:model]
+      #   # => "claude-haiku-4"
+      def resolved_subtask_config
+        @resolved_subtask_config ||= build_resolved_subtask_config
+      end
+
+      private
+
+      # Override lazy_initialize! to always set up parent memory
+      #
+      # The parent Agent only calls initialize_memory when memory_enabled?
+      # is true (memory_directory or memory_adapter set). SubTaskAgent needs
+      # to always assign the parent's memory store, regardless of definition.
+      #
+      # @return [void]
+      def lazy_initialize!
+        return if @initialized
+
+        @loaded_skills = load_skills
+        @base_system_prompt = build_base_system_prompt
+
+        @chat = create_chat
+        configure_chat
+        initialize_memory
+        connect_mcp_servers
+        attach_tools
+
+        @initialized = true
+
+        EventStream.emit(
+          type: "agent_initialized",
+          agent: @id,
+          model: @definition.model,
+          memory_enabled: !@memory_store.nil?,
+          skills_loaded: @loaded_skills.size,
+        )
+      end
+
+      # Use parent's memory store instead of creating a new one
+      #
+      # @return [void]
+      def initialize_memory
+        @memory_store = @parent_memory_store
+      end
+
+      # Skip STM capture — subtask is ephemeral
+      #
+      # @return [void]
+      def capture_turn(*, **)
+        # no-op: subtask turns are not captured in STM
+      end
+
+      # Skip ingestion — read-only memory
+      #
+      # @return [void]
+      def ingest_into_memory(*, **)
+        # no-op: subtask does not write to memory
+      end
+
+      # Skip eviction — no STM to evict
+      #
+      # @return [void]
+      def evict_stm
+        # no-op: subtask has no STM buffer to manage
+      end
+
+      # Pass subtask_depth to Registry so nested SubTask tools know their depth
+      #
+      # @return [void]
+      def attach_tools
+        tool_instances = Tools::Registry.create_all(
+          @definition,
+          memory_store: @memory_store,
+          subtask_depth: @subtask_depth,
+        )
+        mcp_tool_instances = @mcp_connectors.flat_map(&:to_ruby_llm_tools)
+        all_tools = tool_instances + mcp_tool_instances
+        @chat.with_tools(*all_tools) unless all_tools.empty?
+      end
+
+      # Override to use subtask model configuration
+      #
+      # @return [RubyLLM::Chat]
+      def create_chat
+        config = resolved_subtask_config
+        opts = { model: config[:model] }
+
+        if config[:provider]
+          opts[:assume_model_exists] = true
+          opts[:provider] = config[:provider].to_sym
+        end
+
+        if config[:base_url]
+          context = create_context_with_base_url(config[:base_url], config[:provider])
+          context.chat(**opts)
+        else
+          RubyLLM.chat(**opts)
+        end
+      end
+
+      # Override to apply subtask-specific headers and parameters
+      #
+      # @return [void]
+      def configure_chat
+        config = resolved_subtask_config
+        enable_responses_api if @definition.api_version == "v1/responses"
+
+        @chat.with_params(**config[:parameters]) unless config[:parameters].empty?
+        @chat.with_headers(**config[:headers]) unless config[:headers].empty?
+
+        if @base_system_prompt
+          @chat.with_instructions(cacheable_instructions(@base_system_prompt))
+        end
+
+        if @definition.max_concurrent_tools
+          @chat.with_tool_concurrency(:async, max: @definition.max_concurrent_tools)
+        end
+
+        register_event_callbacks
+        register_tool_callbacks
+      end
+
+      # Build the resolved configuration hash
+      #
+      # @return [Hash]
+      def build_resolved_subtask_config
+        global = Configuration.instance
+        defn = @definition
+
+        # Resolution: agent-level > global config > parent definition
+        {
+          model: defn.subtask_model || global.subtask_model || defn.model,
+          provider: defn.subtask_provider || global.subtask_provider || defn.provider,
+          base_url: defn.subtask_base_url || global.subtask_base_url || defn.base_url,
+          headers: merge_headers(defn, global),
+          parameters: merge_parameters(defn, global),
+        }
+      end
+
+      # Merge headers with precedence: agent subtask > global subtask > parent
+      #
+      # @param defn [AgentDefinition]
+      # @param global [Configuration]
+      # @return [Hash]
+      def merge_headers(defn, global)
+        result = defn.headers.dup
+        result.merge!(global.subtask_headers) unless global.subtask_headers.empty?
+        result.merge!(defn.subtask_headers) unless defn.subtask_headers.empty?
+        result
+      end
+
+      # Merge parameters with precedence: agent subtask > global subtask > parent
+      #
+      # @param defn [AgentDefinition]
+      # @param global [Configuration]
+      # @return [Hash]
+      def merge_parameters(defn, global)
+        result = defn.parameters.dup
+        result.merge!(global.subtask_parameters) unless global.subtask_parameters.empty?
+        result.merge!(defn.subtask_parameters) unless defn.subtask_parameters.empty?
+        result
+      end
+    end
+  end
+end

data/lib/swarm_sdk/v3/tools/base.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module V3
+    module Tools
+      # Base class for all V3 tools
+      #
+      # Provides:
+      # - Declarative removability control
+      # - Common path resolution
+      # - Standard error formatting
+      #
+      class Base < RubyLLM::Tool
+        class << self
+          # Declare what parameters this tool needs for instantiation
+          #
+          # Override in subclasses to declare constructor requirements.
+          # The Registry uses this to inject the right parameters.
+          #
+          # @return [Array<Symbol>] Required parameter names
+          #
+          # @example
+          #   def self.creation_requirements
+          #     [:agent_name, :directory]
+          #   end
+          def creation_requirements
+            []
+          end
+        end
+
+        # Derive a clean tool name from the unqualified class name
+        #
+        # RubyLLM's default converts `SwarmSDK::V3::Tools::Read` into
+        # `swarm_s_d_k--v3--tools--read`. This override returns just the
+        # final class name (e.g., `"Read"`), keeping tool names short and
+        # avoiding wasted tokens on every tool call round-trip.
+        #
+        # @return [String] Unqualified class name
+        #
+        # @example
+        #   SwarmSDK::V3::Tools::Read.new(...).name #=> "Read"
+        #   SwarmSDK::V3::Tools::SubTask.new(...).name #=> "SubTask"
+        def name
+          self.class.name.split("::").last
+        end
+
+        private
+
+        # Resolve a path relative to the agent's directory
+        #
+        # Absolute paths are returned as-is. Relative paths are resolved
+        # against the agent's working directory.
+        #
+        # @param path [String] Path to resolve
+        # @return [String] Absolute path
+        def resolve_path(path)
+          return path if path.to_s.start_with?("/")
+
+          File.expand_path(path, @directory)
+        end
+
+        # Format a validation error response
+        #
+        # @param message [String] Error description
+        # @return [String] Formatted error wrapped in tool_use_error tags
+        def validation_error(message)
+          "<tool_use_error>InputValidationError: #{message}</tool_use_error>"
+        end
+
+        # Format a general error response
+        #
+        # @param message [String] Error description
+        # @return [String] Formatted error prefixed with "Error:"
+        def error(message)
+          "Error: #{message}"
+        end
+      end
+    end
+  end
+end

data/lib/swarm_sdk/v3/tools/bash.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module V3
+    module Tools
+      # Bash tool for executing shell commands
+      #
+      # Executes commands in a subprocess with timeout support.
+      # Commands run in the agent's working directory.
+      class Bash < Base
+        class << self
+          # @return [Array<Symbol>] Constructor requirements
+          def creation_requirements
+            [:directory]
+          end
+        end
+
+        # Commands that are always blocked for safety
+        ALWAYS_BLOCKED_COMMANDS = [
+          %r{^rm\s+-rf\s+/$},
+        ].freeze
+
+        description <<~DESC
+          Executes a bash command with optional timeout.
+
+          Use for terminal operations like git, npm, docker, etc.
+          DO NOT use for file operations — use Read, Write, Edit, Grep, Glob instead.
+
+          Usage notes:
+          - Default timeout: 120 seconds (max: 600 seconds)
+          - Output truncated at 30000 characters
+          - Quote file paths with spaces
+          - Use && to chain dependent commands
+        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 (5-10 words)",
+          required: false
+
+        param :timeout,
+          type: "number",
+          desc: "Optional timeout in milliseconds (max 600000)",
+          required: false
+
+        # @param directory [String] Working directory for command execution
+        def initialize(directory:)
+          super()
+          @directory = File.expand_path(directory)
+        end
+
+        # Execute a shell command
+        #
+        # @param command [String] The command to run
+        # @param description [String, nil] Human-readable description
+        # @param timeout [Integer, nil] Timeout in milliseconds
+        # @return [String] Command output or error
+        def execute(command:, description: nil, timeout: nil)
+          return validation_error("command is required") if command.nil? || command.empty?
+
+          blocked = ALWAYS_BLOCKED_COMMANDS.find { |pattern| pattern.match?(command) }
+          return blocked_command_error(command) if blocked
+
+          config = Configuration.instance
+          timeout_ms = timeout || config.bash_command_timeout
+          timeout_ms = [timeout_ms, config.bash_command_max_timeout].min
+          timeout_seconds = timeout_ms / 1000.0
+
+          stdout, stderr, exit_status = run_command(command, timeout_seconds)
+          return stdout if stdout.start_with?("Error:") # Error from run_command
+
+          output = format_output(command, description, stdout, stderr, exit_status)
+
+          max_output = config.output_character_limit
+          if output.length > max_output
+            output = "#{output[0...max_output]}\n\n<system-reminder>Output truncated at #{max_output} characters.</system-reminder>"
+          end
+
+          output
+        rescue StandardError => e
+          error("Unexpected error: #{e.class.name} - #{e.message}")
+        end
+
+        private
+
+        # Run a command in a subprocess
+        #
+        # Tracks the subprocess PID so it can be terminated if the command
+        # is interrupted (Async::Stop) or times out. The ensure block
+        # guarantees cleanup because Async::Stop bypasses rescue StandardError.
+        #
+        # @param command [String] Shell command
+        # @param timeout_seconds [Float] Timeout
+        # @return [Array(String, String, Integer)] stdout, stderr, exit status
+        def run_command(command, timeout_seconds)
+          pid = nil
+          completed = false
+          stdout = +""
+          stderr = +""
+          exit_status = nil
+
+          Timeout.timeout(timeout_seconds) do
+            Dir.chdir(@directory) do
+              Open3.popen3(command) do |stdin, out, err, wait_thr|
+                pid = wait_thr.pid
+                stdin.close
+                stdout = out.read || ""
+                stderr = err.read || ""
+                exit_status = wait_thr.value.exitstatus
+                completed = true
+              end
+            end
+          end
+
+          [stdout, stderr, exit_status]
+        rescue Timeout::Error
+          [error("Command timed out after #{timeout_seconds} seconds."), "", 1]
+        rescue Errno::ENOENT => e
+          [error("Command not found: #{e.message}"), "", 1]
+        rescue Errno::EACCES
+          [error("Permission denied: Cannot execute command '#{command}'"), "", 1]
+        ensure
+          terminate_process(pid) unless completed
+        end
+
+        # Terminate a subprocess that didn't complete normally
+        #
+        # Sends TERM for graceful shutdown. Called from ensure block on
+        # timeout, interruption (Async::Stop), or other abnormal exit.
+        #
+        # @param pid [Integer, nil] Process ID to terminate
+        # @return [void]
+        def terminate_process(pid)
+          return unless pid
+
+          Process.kill("TERM", pid)
+          Process.wait(pid, Process::WNOHANG)
+        rescue Errno::ESRCH, Errno::ECHILD
+          # Process already exited
+        end
+
+        # Format command output
+        #
+        # @param command [String] Original command
+        # @param description [String, nil] Command description
+        # @param stdout [String] Standard output
+        # @param stderr [String] Standard error
+        # @param exit_status [Integer] Exit code
+        # @return [String] Formatted output
+        def format_output(command, description, stdout, stderr, exit_status)
+          parts = []
+          parts << "Running: #{description}" if description
+          parts << "$ #{command}"
+          parts << ""
+          parts << "Exit code: #{exit_status}"
+          parts << "\nSTDOUT:\n#{stdout.chomp}" unless stdout.empty?
+          parts << "\nSTDERR:\n#{stderr.chomp}" unless stderr.empty?
+          parts.join("\n")
+        end
+
+        # @param command [String] Blocked command
+        # @return [String] Error message
+        def blocked_command_error(command)
+          error("Command blocked for safety reasons: #{command}")
+        end
+      end
+    end
+  end
+end

data/lib/swarm_sdk/v3/tools/clock.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module V3
+    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
+        description <<~DESC
+          Get current date and time.
+
+          Returns current date, time, day of week, and ISO 8601 timestamp.
+          Use when you need temporal information for decisions or context.
+        DESC
+
+        # @return [String] Formatted date/time information
+        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
+end

data/lib/swarm_sdk/v3/tools/edit.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module V3
+    module Tools
+      # Edit tool for performing exact string replacements in files
+      #
+      # Uses exact string matching to find and replace content.
+      # Requires the file to have been read first via the Read tool.
+      class Edit < Base
+        class << self
+          # @return [Array<Symbol>] Constructor requirements
+          def creation_requirements
+            [:agent_name, :directory, :read_tracker]
+          end
+        end
+
+        description <<~DESC
+          Performs exact string replacements in files.
+          You must use Read on a file before editing it.
+          The edit will FAIL if old_string is not unique — provide more context or use replace_all.
+
+          Path handling:
+          - Relative paths resolve against your working directory
+          - Absolute paths (starting with /) are used as-is
+        DESC
+
+        param :file_path,
+          type: "string",
+          desc: "Path to the file to edit",
+          required: true
+
+        param :old_string,
+          type: "string",
+          desc: "The exact text to replace (must match exactly including whitespace)",
+          required: true
+
+        param :new_string,
+          type: "string",
+          desc: "The text to replace it with (must be different from old_string)",
+          required: true
+
+        param :replace_all,
+          type: "boolean",
+          desc: "Replace all occurrences of old_string (default false)",
+          required: false
+
+        # @param agent_name [Symbol, String] Agent identifier
+        # @param directory [String] Agent's working directory
+        # @param read_tracker [ReadTracker] Shared read tracker for enforcement
+        def initialize(agent_name:, directory:, read_tracker:)
+          super()
+          @agent_name = agent_name.to_sym
+          @directory = File.expand_path(directory)
+          @read_tracker = read_tracker
+        end
+
+        # Execute file edit
+        #
+        # @param file_path [String] Path to the file
+        # @param old_string [String] Text to find
+        # @param new_string [String] Replacement text
+        # @param replace_all [Boolean] Replace all occurrences
+        # @return [String] Success or error message
+        def execute(file_path:, old_string:, new_string:, replace_all: false)
+          return validation_error("file_path is required") if file_path.nil? || file_path.to_s.strip.empty?
+          return validation_error("old_string is required") if old_string.nil? || old_string.empty?
+          return validation_error("new_string is required") if new_string.nil?
+          return validation_error("old_string and new_string must be different.") if old_string == new_string
+
+          resolved_path = resolve_path(file_path)
+          return validation_error("File does not exist: #{file_path}") unless File.exist?(resolved_path)
+
+          unless @read_tracker.file_read?(@agent_name, resolved_path)
+            return validation_error(
+              "Cannot edit file without reading it first. " \
+                "Use the Read tool on '#{file_path}' before editing.",
+            )
+          end
+
+          content = File.read(resolved_path, encoding: "UTF-8")
+
+          unless content.include?(old_string)
+            return validation_error("old_string not found in file. Make sure it matches exactly, including all whitespace and indentation.")
+          end
+
+          occurrences = content.scan(old_string).count
+
+          if !replace_all && occurrences > 1
+            return validation_error(
+              "Found #{occurrences} occurrences of old_string. " \
+                "Provide more context to make the match unique, or use replace_all: true.",
+            )
+          end
+
+          new_content = replace_all ? content.gsub(old_string, new_string) : content.sub(old_string, new_string)
+          File.write(resolved_path, new_content, encoding: "UTF-8")
+
+          replaced_count = replace_all ? occurrences : 1
+          "Successfully replaced #{replaced_count} occurrence(s) in #{file_path}"
+        rescue Encoding::InvalidByteSequenceError, Encoding::UndefinedConversionError
+          error("File contains invalid UTF-8. Cannot edit binary files.")
+        rescue Errno::EACCES
+          error("Permission denied: Cannot read or write file '#{file_path}'")
+        rescue StandardError => e
+          error("Unexpected error editing file: #{e.class.name} - #{e.message}")
+        end
+      end
+    end
+  end
+end