swarm_sdk 2.7.14 → 3.0.0.alpha2

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

data/lib/swarm_sdk/v3.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+require "bundler"
+require "cgi"
+require "digest"
+require "English"
+require "fileutils"
+require "json"
+require "open3"
+require "pathname"
+require "securerandom"
+require "set"
+require "time"
+require "timeout"
+
+require "async"
+require "async/barrier"
+require "async/semaphore"
+require "mcp"
+require "ruby_llm"
+
+# Load ruby_llm compatibility patches (shared gem infrastructure)
+require_relative "ruby_llm_patches/init"
+
+require "zeitwerk"
+
+module SwarmSDK
+  # V3 is the next-generation agent primitive with built-in memory.
+  #
+  # Self-contained module with its own Zeitwerk loader and zero dependencies
+  # on V2 code. The core insight: the LLM's context window is a staging area,
+  # not the whole brain. Older turns get consolidated into memory cards, and
+  # retrieval brings relevant memory back into working context on demand.
+  #
+  # @example Basic usage
+  #   require "swarm_sdk/v3"
+  #
+  #   definition = SwarmSDK::V3::AgentDefinition.new(
+  #     name: :assistant,
+  #     description: "A helpful assistant",
+  #     model: "claude-sonnet-4",
+  #     tools: [:Read, :Write, :Edit, :Bash, :Grep, :Glob],
+  #     memory_directory: ".swarm/memory",
+  #   )
+  #
+  #   agent = SwarmSDK::V3::Agent.new(definition)
+  #   response = agent.ask("Build a login page")
+  #
+  # @example Without memory (pure conversation)
+  #   definition = SwarmSDK::V3::AgentDefinition.new(
+  #     name: :chat,
+  #     description: "Simple chat agent",
+  #     model: "claude-sonnet-4",
+  #   )
+  #
+  #   agent = SwarmSDK::V3::Agent.new(definition)
+  #   response = agent.ask("Hello!")
+  module V3
+    class Error < StandardError; end
+    class ConfigurationError < Error; end
+    class ToolExecutionError < Error; end
+    class MemoryError < Error; end
+
+    class << self
+      # Build a single V3 Agent from a DSL block
+      #
+      # Convenience entry point that delegates to {AgentBuilder.build}.
+      # Returns an initialized Agent ready for use with {Agent#ask}.
+      #
+      # @yield DSL block evaluated on an {AgentBuilder} instance
+      # @return [Agent] Initialized agent
+      # @raise [ConfigurationError] If required fields are missing
+      #
+      # @example
+      #   agent = SwarmSDK::V3.agent do
+      #     name :assistant
+      #     description "A helpful assistant"
+      #     tools :Read, :Write, :Edit
+      #     streaming true
+      #
+      #     memory do
+      #       directory ".swarm/memory"
+      #     end
+      #   end
+      #
+      #   agent.ask("Hello!")
+      def agent(&block)
+        AgentBuilder.build(&block)
+      end
+
+      # Configure V3 global settings
+      #
+      # Convenience wrapper around {Configuration.configure}. Yields the
+      # configuration instance and applies provider settings to RubyLLM.
+      #
+      # @yield [Configuration] The configuration instance
+      # @return [Configuration]
+      #
+      # @example
+      #   SwarmSDK::V3.configure do |config|
+      #     config.default_model = "claude-sonnet-4"
+      #     config.anthropic_api_key = ENV["ANTHROPIC_API_KEY"]
+      #     config.default_tools = [:Think, :Clock]
+      #   end
+      def configure(&block)
+        Configuration.configure(&block)
+      end
+
+      # Access the global configuration instance
+      #
+      # @return [Configuration]
+      #
+      # @example
+      #   model = SwarmSDK::V3.configuration.default_model
+      def configuration
+        Configuration.instance
+      end
+
+      # Reset configuration to defaults
+      #
+      # @return [void]
+      def reset_configuration!
+        Configuration.reset!
+      end
+    end
+  end
+end
+
+# V3 Zeitwerk setup:
+# When loaded via V2 (require "swarm_sdk"), the V2 loader already manages
+# lib/swarm_sdk/ including v3/, so we skip to avoid conflicts.
+# When loaded standalone (require "swarm_sdk/v3"), creates its own loader.
+v3_dir = File.join(__dir__, "v3")
+already_managed = false
+Zeitwerk::Registry.loaders.each do |loader|
+  loader.dirs.each { |dir| already_managed = true if v3_dir.start_with?(dir) }
+end
+
+unless already_managed
+  v3_loader = Zeitwerk::Loader.new
+  v3_loader.tag = "swarm_sdk_v3"
+  v3_loader.push_dir(v3_dir, namespace: SwarmSDK::V3)
+  v3_loader.inflector.inflect("mcp" => "MCP")
+  v3_loader.setup
+end