swarm_sdk 2.7.14 → 3.0.0.alpha1

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

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module V3
+    module Tools
+      # Registry for V3 tools (built-in and custom)
+      #
+      # Maps tool names (symbols) to their V3 tool classes.
+      # Provides lookup, validation, factory, and custom tool registration.
+      #
+      # Tools fall into categories based on creation requirements:
+      # 1. **No params**: Simple tools (Think, Clock)
+      # 2. **Directory only**: Tools needing working directory (Bash, Grep, Glob)
+      # 3. **Agent context**: Tools needing agent name + directory (Read, Write, Edit)
+      #
+      # @example Look up a tool
+      #   klass = Registry.get(:Read)
+      #
+      # @example Create a tool instance
+      #   tool = Registry.create(:Read, agent_name: :backend, directory: "/app")
+      #
+      # @example Register a custom tool
+      #   Registry.register(:MyTool, MyCustomTool)
+      #
+      # @example List available tools
+      #   Registry.available_names  #=> [:Read, :Write, :Edit, ...]
+      class Registry
+        class << self
+          # Lazily-built tool mapping
+          #
+          # Uses lazy evaluation so tool classes are only resolved when first accessed,
+          # allowing Zeitwerk to load them on demand. Mutable to support custom registration.
+          #
+          # @return [Hash<Symbol, Class>] Tool name to class mapping
+          def builtin_tools
+            @builtin_tools ||= {
+              Read: SwarmSDK::V3::Tools::Read,
+              Write: SwarmSDK::V3::Tools::Write,
+              Edit: SwarmSDK::V3::Tools::Edit,
+              Bash: SwarmSDK::V3::Tools::Bash,
+              Grep: SwarmSDK::V3::Tools::Grep,
+              Glob: SwarmSDK::V3::Tools::Glob,
+              Think: SwarmSDK::V3::Tools::Think,
+              Clock: SwarmSDK::V3::Tools::Clock,
+              SubTask: SwarmSDK::V3::Tools::SubTask,
+            }
+          end
+
+          # Register a custom tool
+          #
+          # @param name [Symbol, String] Tool name
+          # @param klass [Class] Tool class (must inherit from Base or RubyLLM::Tool)
+          # @return [void]
+          # @raise [ConfigurationError] If name is already taken by a built-in tool
+          #
+          # @example
+          #   Registry.register(:WebSearch, MyWebSearchTool)
+          def register(name, klass)
+            name_sym = name.to_sym
+            builtin_tools[name_sym] = klass
+          end
+
+          # Reset registry to built-in tools only
+          #
+          # Removes all custom tool registrations. Useful for test cleanup.
+          #
+          # @return [void]
+          def reset!
+            @builtin_tools = nil
+          end
+
+          # Get tool class by name
+          #
+          # Respects the `registered_tools` configuration filter. If `registered_tools`
+          # is set, only those tools are visible.
+          #
+          # @param name [Symbol, String] Tool name
+          # @return [Class, nil] Tool class or nil if not found/filtered
+          #
+          # @example
+          #   Registry.get(:Read)  #=> SwarmSDK::V3::Tools::Read
+          def get(name)
+            name_sym = name.to_sym
+            allowed = Configuration.instance.registered_tools
+            return if allowed && !allowed.map(&:to_sym).include?(name_sym)
+
+            builtin_tools[name_sym]
+          end
+
+          # Create a tool instance with context
+          #
+          # Uses the tool's `creation_requirements` to determine constructor params.
+          #
+          # @param name [Symbol, String] Tool name
+          # @param context [Hash] Available context for tool creation
+          # @option context [Symbol] :agent_name Agent identifier
+          # @option context [String] :directory Agent's working directory
+          # @return [RubyLLM::Tool] Instantiated tool
+          # @raise [ConfigurationError] If tool unknown or requirements unmet
+          #
+          # @example
+          #   tool = Registry.create(:Read, agent_name: :backend, directory: "/app")
+          def create(name, **context)
+            name_sym = name.to_sym
+            tool_class = get(name_sym)
+
+            raise ConfigurationError, "Unknown tool: #{name}" unless tool_class
+
+            if tool_class.respond_to?(:creation_requirements) && tool_class.creation_requirements.any?
+              requirements = tool_class.creation_requirements
+              params = extract_params(requirements, context, name)
+              tool_class.new(**params)
+            else
+              tool_class.new
+            end
+          end
+
+          # Create all tools for an agent definition
+          #
+          # Merges the agent's tools with global `default_tools` from configuration.
+          # Filters against `registered_tools` if configured.
+          #
+          # @param definition [AgentDefinition] Agent definition with tool list
+          # @return [Array<RubyLLM::Tool>] Instantiated tools
+          # @raise [ConfigurationError] If any tool is unknown
+          #
+          # @example
+          #   tools = Registry.create_all(definition)
+          def create_all(definition, memory_store: nil, subtask_depth: 0)
+            # Create shared read tracker for cross-tool enforcement
+            read_tracker = ReadTracker.new
+
+            context = {
+              agent_name: definition.name,
+              directory: definition.directory,
+              read_tracker: read_tracker,
+              memory_store: memory_store,
+              agent_definition: definition,
+              subtask_depth: subtask_depth,
+            }
+
+            config = Configuration.instance
+
+            # Start with the agent's declared tools + global default_tools
+            tool_names = definition.tools.dup
+            config.default_tools.each do |name|
+              tool_names << name.to_sym unless tool_names.include?(name.to_sym)
+            end
+
+            # Filter against registered_tools if configured
+            if config.registered_tools
+              allowed = config.registered_tools.map(&:to_sym)
+              tool_names.select! { |name| allowed.include?(name) }
+            end
+
+            tool_names.uniq.map { |name| create(name, **context) }
+          end
+
+          # Check if a tool exists (respects registered_tools filter)
+          #
+          # @param name [Symbol, String] Tool name
+          # @return [Boolean]
+          def exists?(name)
+            !get(name.to_sym).nil?
+          end
+
+          # Get all available tool names (respects registered_tools filter)
+          #
+          # @return [Array<Symbol>]
+          def available_names
+            allowed = Configuration.instance.registered_tools
+            names = builtin_tools.keys
+            names.select! { |n| allowed.map(&:to_sym).include?(n) } if allowed
+            names
+          end
+
+          # Validate tool names
+          #
+          # @param names [Array<Symbol, String>] Tool names to validate
+          # @return [Array<Symbol>] Invalid tool names
+          def validate(names)
+            names.map(&:to_sym).reject { |name| exists?(name) }
+          end
+
+          private
+
+          # Extract parameters from context for tool construction
+          #
+          # Includes each declared requirement that exists in the context.
+          # Missing keys are skipped — the tool constructor's own defaults
+          # and Ruby's `missing keyword` error handle validation naturally.
+          #
+          # @param requirements [Array<Symbol>] Parameter names the tool accepts
+          # @param context [Hash] Available context
+          # @param _tool_name [Symbol] Tool name (unused, kept for interface stability)
+          # @return [Hash] Parameters for constructor
+          def extract_params(requirements, context, _tool_name)
+            params = {}
+            requirements.each do |req|
+              params[req] = context[req] if context.key?(req)
+            end
+            params
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module V3
+    module Tools
+      # SubTask tool for spawning focused subtask agents
+      #
+      # Allows an agent to spawn a copy of itself for a focused subtask.
+      # The subtask agent shares the parent's memory (read-only), MCP
+      # connections, and skill access. It runs in the same process.
+      #
+      # SubTask is opt-in — agents must include :SubTask in their tools list.
+      # This prevents accidental cost explosion from unintended spawning.
+      #
+      # ## Depth control
+      #
+      # Subtasks track nesting depth. The maximum depth is controlled by
+      # {Configuration#max_subtask_depth} (default: 1, meaning the parent
+      # can spawn subtasks, but subtasks cannot spawn further subtasks).
+      #
+      # @example Agent definition with SubTask
+      #   AgentDefinition.new(
+      #     name: :researcher,
+      #     description: "Research agent",
+      #     tools: [:Read, :Grep, :Glob, :Think, :SubTask],
+      #   )
+      class SubTask < Base
+        class << self
+          # @return [Array<Symbol>] Constructor requirements
+          def creation_requirements
+            [:agent_definition, :memory_store, :directory, :subtask_depth]
+          end
+        end
+
+        # @param agent_definition [AgentDefinition] Parent agent's definition
+        # @param memory_store [Memory::Store, nil] Parent's memory store
+        # @param directory [String] Working directory
+        # @param subtask_depth [Integer] Current nesting depth
+        def initialize(agent_definition:, memory_store: nil, directory: ".", subtask_depth: 0)
+          super()
+          @agent_definition = agent_definition
+          @memory_store = memory_store
+          @directory = directory
+          @subtask_depth = subtask_depth
+        end
+
+        description <<~DESC
+          Spawn a focused subtask to handle a specific piece of work.
+
+          The subtask runs as a copy of you with the same tools, skills, and MCP
+          connections, but in an **isolated context window**. Results are returned
+          as a summary, keeping your main context clean.
+
+          ## When to use SubTask
+
+          **Strongly prefer SubTask when:**
+          - Reading or analyzing multiple files (3+ files)
+          - Making multiple MCP tool calls (MCP operations are context-heavy)
+          - Searching across a codebase (grep/glob + read patterns)
+          - Performing any operation that would return large outputs
+          - Investigating tangential questions before returning to main task
+
+          **Use direct tools when:**
+          - Single, quick operations (one file read, one simple command)
+          - You need the raw output for immediate follow-up in the same turn
+
+          ## Context efficiency
+
+          Each subtask gets a fresh context window. Instead of accumulating
+          50k+ tokens of tool outputs in your context, you receive a focused
+          summary. This keeps you effective over long conversations.
+
+          ## Example patterns
+
+          Instead of: Read file1, Read file2, Read file3, Grep for X, analyze
+          Do: SubTask("Analyze auth system", "Read the auth files and grep for
+              login patterns, summarize the authentication flow")
+
+          Instead of: Multiple MCP tool calls to external services
+          Do: SubTask("Gather external data", "Use the MCP tools to fetch X, Y, Z
+              and return the relevant findings")
+
+          ## Memory access
+
+          The subtask has read-only access to your memory — it can retrieve
+          context but cannot write new memories.
+
+          Be specific in your instructions. The subtask sees only what you
+          provide in the instructions field, plus any memory it retrieves.
+        DESC
+
+        param :title,
+          type: "string",
+          desc: "Short title for the subtask (used in logging)",
+          required: true
+
+        param :instructions,
+          type: "string",
+          desc: "Detailed instructions for the subtask. Be specific — the subtask only sees these instructions and its retrieved memory.",
+          required: true
+
+        # Execute the SubTask tool
+        #
+        # Spawns a SubTaskAgent, runs the instructions, and returns the result.
+        # The subtask agent is always cleaned up via ensure block.
+        #
+        # @param title [String] Short title for logging
+        # @param instructions [String] Detailed instructions for the subtask
+        # @return [String] Subtask result or error message
+        def execute(title:, instructions:, **_kwargs)
+          return validation_error("title is required") if title.to_s.strip.empty?
+          return validation_error("instructions are required") if instructions.to_s.strip.empty?
+
+          next_depth = @subtask_depth + 1
+          max_depth = Configuration.instance.max_subtask_depth
+
+          if next_depth > max_depth
+            return error(
+              "Maximum subtask depth (#{max_depth}) exceeded. " \
+                "Cannot spawn nested subtask at depth #{next_depth}.",
+            )
+          end
+
+          agent = SubTaskAgent.new(
+            @agent_definition,
+            parent_memory_store: @memory_store,
+            subtask_depth: next_depth,
+          )
+
+          EventStream.emit(
+            type: "subtask_spawned",
+            agent: @agent_definition.name,
+            subtask_agent: agent.id,
+            title: title,
+            depth: next_depth,
+          )
+
+          prompt = <<~PROMPT.strip
+            # SubTask: #{title}
+
+            #{instructions}
+          PROMPT
+
+          response = agent.ask(prompt)
+          format_result(title, response)
+        rescue StandardError => e
+          EventStream.emit(
+            type: "subtask_failed",
+            agent: @agent_definition.name,
+            subtask_agent: agent&.id,
+            title: title,
+            error: "#{e.class}: #{e.message}",
+          )
+          error("Subtask '#{title}' failed: #{e.class}: #{e.message}")
+        ensure
+          agent&.clear
+        end
+
+        private
+
+        # Format a successful subtask result
+        #
+        # @param title [String] Subtask title
+        # @param response [RubyLLM::Message] LLM response
+        # @return [String] Formatted result
+        def format_result(title, response)
+          EventStream.emit(
+            type: "subtask_completed",
+            agent: @agent_definition.name,
+            title: title,
+            success: true,
+          )
+
+          <<~RESULT.strip
+            ## SubTask Result: #{title}
+
+            #{response&.content || "(no response)"}
+          RESULT
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module V3
+    module Tools
+      # Think tool for explicit reasoning and planning
+      #
+      # Allows the agent to write down thoughts, plans, and intermediate
+      # calculations. These thoughts become part of the conversation context,
+      # enabling better reasoning through complex problems.
+      #
+      # When the agent has memory enabled, Think retrieves relevant memories
+      # for the thought content and returns them alongside "Thought noted."
+      # This gives the agent access to its long-term knowledge while reasoning.
+      # Without memory, Think behaves as a simple acknowledgment.
+      #
+      # Think does NOT write to memory — the existing turn-level async
+      # ingestion pipeline already captures tool call arguments (including
+      # Think's thoughts), so Think content is automatically persisted.
+      class Think < Base
+        class << self
+          # @return [Array<Symbol>] Constructor requirements
+          def creation_requirements
+            [:memory_store]
+          end
+        end
+
+        # @param memory_store [Memory::Store, nil] Memory store for retrieval
+        def initialize(memory_store: nil)
+          super()
+          @memory_store = memory_store
+        end
+
+        description <<~DESC
+          Use this tool to think through problems step by step before acting.
+
+          This is your working memory — record your thoughts, plans, strategies,
+          and intermediate calculations. Using this tool leads to significantly
+          better outcomes and more accurate solutions.
+
+          Use it frequently:
+          - Before starting any task
+          - When doing arithmetic or counting
+          - After reading files to process what you learned
+          - Between steps to track progress
+          - When debugging to trace issues
+
+          Your thoughts persist throughout the session as conversation history.
+        DESC
+
+        param :thoughts,
+          type: "string",
+          desc: "Your thoughts, plans, calculations, or any notes you want to record",
+          required: true
+
+        # Execute the Think tool
+        #
+        # When memory is available, searches for cards relevant to the thought
+        # content and returns them as context for the agent's reasoning.
+        #
+        # @param thoughts [String] The agent's thoughts
+        # @return [String] Acknowledgment with optional related memories
+        def execute(thoughts:, **_kwargs)
+          return "Thought noted." unless @memory_store
+
+          cards = @memory_store.search(thoughts, top_k: 5)
+          format_response(cards)
+        end
+
+        private
+
+        # Format the response with optional related memories
+        #
+        # @param cards [Array<Card>] Retrieved memory cards
+        # @return [String] Formatted response
+        def format_response(cards)
+          return "Thought noted." if cards.empty?
+
+          lines = ["Thought noted.", "", "Related memories:"]
+          cards.each do |card|
+            lines << "- [#{card.type.to_s.capitalize}] #{card.text}"
+          end
+          lines.join("\n")
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module V3
+    module Tools
+      # Write tool for writing content to files
+      #
+      # Creates new files or overwrites existing files.
+      # Enforces read-before-write for existing files via the Read tool's tracking.
+      class Write < Base
+        class << self
+          # @return [Array<Symbol>] Constructor requirements
+          def creation_requirements
+            [:agent_name, :directory, :read_tracker]
+          end
+        end
+
+        description <<~DESC
+          Writes a file to the local filesystem.
+          Overwrites existing files. You MUST use Read first on existing files.
+          ALWAYS prefer editing existing files. NEVER write new files unless required.
+
+          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 write",
+          required: true
+
+        param :content,
+          type: "string",
+          desc: "The content to write to the file",
+          required: true
+
+        # @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 write
+        #
+        # @param file_path [String] Path to the file
+        # @param content [String] Content to write
+        # @return [String] Success or error message
+        def execute(file_path:, content:)
+          return validation_error("file_path is required") if file_path.nil? || file_path.to_s.strip.empty?
+          return validation_error("content is required") if content.nil?
+
+          resolved_path = resolve_path(file_path)
+          file_exists = File.exist?(resolved_path)
+
+          if file_exists && !@read_tracker.file_read?(@agent_name, resolved_path)
+            return validation_error(
+              "Cannot write to existing file without reading it first. " \
+                "Use the Read tool on '#{file_path}' before overwriting.",
+            )
+          end
+
+          parent_dir = File.dirname(resolved_path)
+          FileUtils.mkdir_p(parent_dir) unless File.directory?(parent_dir)
+
+          File.write(resolved_path, content, encoding: "UTF-8")
+
+          byte_size = content.bytesize
+          line_count = content.lines.count
+          action = file_exists ? "overwrote" : "created"
+
+          "Successfully #{action} file: #{file_path} (#{line_count} lines, #{byte_size} bytes)"
+        rescue Errno::EACCES
+          error("Permission denied: Cannot write to file '#{file_path}'")
+        rescue Errno::EISDIR
+          error("Path is a directory, not a file.")
+        rescue StandardError => e
+          error("Unexpected error writing file: #{e.class.name} - #{e.message}")
+        end
+      end
+    end
+  end
+end