swarm_sdk 2.7.14 → 3.0.0.alpha1

data/lib/swarm_sdk/tools/write.rb

@@ -1,112 +0,0 @@
-# frozen_string_literal: true
-
-module SwarmSDK
-  module Tools
-    # Write tool for writing content to files
-    #
-    # Creates new files or overwrites existing files.
-    # Enforces read-before-write rule for existing files.
-    # Includes validation and usage guidelines via system reminders.
-    class Write < Base
-      include PathResolver
-
-      # Factory pattern: declare what parameters this tool needs for instantiation
-      class << self
-        def creation_requirements
-          [:agent_name, :directory]
-        end
-      end
-
-      description <<~DESC
-        Writes a file to the local filesystem.
-        This tool will overwrite the existing file if there is one at the provided path.
-        If this is an existing file, you MUST use the Read tool first to read the file's contents.
-        This tool will fail if you did not read the file first.
-        ALWAYS prefer editing existing files in the codebase. NEVER write new files unless explicitly required.
-        NEVER proactively create documentation files (*.md) or README files. Only create documentation files if explicitly requested by the User.
-        Only use emojis if the user explicitly requests it. Avoid writing emojis to files unless asked.
-
-        IMPORTANT - Path Handling:
-        - Relative paths (e.g., "tmp/file.txt", "src/main.rb") are resolved relative to your agent's working directory
-        - Absolute paths (e.g., "/tmp/file.txt", "/etc/passwd") are treated as system absolute paths
-        - When the user says "tmp/file.txt" they mean the tmp directory in your working directory, NOT /tmp
-        - Only use absolute paths (starting with /) when explicitly referring to system-level paths
-      DESC
-
-      param :file_path,
-        type: "string",
-        desc: "Path to the file. Use relative paths (e.g., 'tmp/file.txt') for files in your working directory, or absolute paths (e.g., '/etc/passwd') for system files.",
-        required: true
-
-      param :content,
-        type: "string",
-        desc: "The content to write to the file",
-        required: true
-
-      # Initialize the Write tool for a specific agent
-      #
-      # @param agent_name [Symbol, String] The agent identifier
-      # @param directory [String] Agent's working directory
-      def initialize(agent_name:, directory:)
-        super()
-        initialize_agent_context(agent_name: agent_name, directory: directory)
-      end
-
-      # Override name to return simple "Write" instead of full class path
-      def name
-        "Write"
-      end
-
-      def execute(file_path:, content:)
-        # Validate inputs
-        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?
-
-        # CRITICAL: Resolve path against agent directory
-        resolved_path = resolve_path(file_path)
-
-        # Check if file already exists (use resolved path)
-        file_exists = File.exist?(resolved_path)
-
-        # Enforce read-before-write for existing files (use resolved path)
-        if file_exists && !Stores::ReadTracker.file_read?(@agent_name, resolved_path)
-          return validation_error(
-            "Cannot write to existing file without reading it first. " \
-              "You must use the Read tool on '#{file_path}' before overwriting it. " \
-              "This ensures you have context about the file's current contents.",
-          )
-        end
-
-        # Create parent directory if it doesn't exist (use resolved path)
-        parent_dir = File.dirname(resolved_path)
-        FileUtils.mkdir_p(parent_dir) unless File.directory?(parent_dir)
-
-        # Write the file (use resolved path)
-        File.write(resolved_path, content, encoding: "UTF-8")
-
-        # Build success message
-        byte_size = content.bytesize
-        line_count = content.lines.count
-        action = file_exists ? "overwrote" : "created"
-
-        message = "Successfully #{action} file: #{file_path} (#{line_count} lines, #{byte_size} bytes)"
-
-        # Add system reminder for overwritten files
-        if file_exists
-          reminder = "<system-reminder>You overwrote an existing file. Make sure this was intentional and that you read the file first if you needed to preserve any content.</system-reminder>"
-          "#{message}\n\n#{reminder}"
-        else
-          message
-        end
-      rescue Errno::EACCES
-        error("Permission denied: Cannot write to file '#{file_path}'")
-      rescue Errno::EISDIR
-        error("Path is a directory, not a file.")
-      rescue Errno::ENOENT => e
-        error("Failed to create parent directory: #{e.message}")
-      rescue StandardError => e
-        error("Unexpected error writing file: #{e.class.name} - #{e.message}")
-      end
-    end
-  end
-end

data/lib/swarm_sdk/transcript_builder.rb

@@ -1,278 +0,0 @@
-# frozen_string_literal: true
-
-module SwarmSDK
-  # Transforms raw log events into LLM-readable conversation transcripts
-  #
-  # TranscriptBuilder converts the structured event log from swarm execution
-  # into a human/LLM-readable format suitable for reflection, analysis, or
-  # memory creation.
-  #
-  # @example Basic usage
-  #   transcript = TranscriptBuilder.build(result.logs)
-  #   # => "USER: Help me with CORS\n\nAGENT [assistant]: ..."
-  #
-  # @example Filter by agents
-  #   transcript = TranscriptBuilder.build(result.logs, agents: [:backend, :database])
-  #
-  # @example Custom options
-  #   transcript = TranscriptBuilder.build(
-  #     result.logs,
-  #     include_tool_results: true,
-  #     max_result_length: 1000,
-  #     include_thinking: false
-  #   )
-  class TranscriptBuilder
-    # Default maximum length for tool result content
-    DEFAULT_MAX_RESULT_LENGTH = 500
-
-    # Default maximum length for tool arguments
-    DEFAULT_MAX_ARGS_LENGTH = 200
-
-    class << self
-      # Build a transcript from log events
-      #
-      # @param logs [Array<Hash>] Array of log events from Result#logs
-      # @param agents [Array<Symbol>, nil] Filter to specific agents (nil = all)
-      # @param include_tool_results [Boolean] Include tool execution results (default: true)
-      # @param include_thinking [Boolean] Include agent_step content/thinking (default: false)
-      # @param max_result_length [Integer] Maximum characters for tool results
-      # @param max_args_length [Integer] Maximum characters for tool arguments
-      # @return [String] Formatted transcript
-      def build(logs, agents: nil, include_tool_results: true, include_thinking: false,
-        max_result_length: DEFAULT_MAX_RESULT_LENGTH, max_args_length: DEFAULT_MAX_ARGS_LENGTH)
-        new(
-          logs,
-          agents: agents,
-          include_tool_results: include_tool_results,
-          include_thinking: include_thinking,
-          max_result_length: max_result_length,
-          max_args_length: max_args_length,
-        ).build
-      end
-    end
-
-    # Initialize a new TranscriptBuilder
-    #
-    # @param logs [Array<Hash>] Array of log events
-    # @param agents [Array<Symbol>, nil] Filter to specific agents
-    # @param include_tool_results [Boolean] Include tool execution results
-    # @param include_thinking [Boolean] Include agent_step content
-    # @param max_result_length [Integer] Maximum characters for tool results
-    # @param max_args_length [Integer] Maximum characters for tool arguments
-    def initialize(logs, agents: nil, include_tool_results: true, include_thinking: false,
-      max_result_length: DEFAULT_MAX_RESULT_LENGTH, max_args_length: DEFAULT_MAX_ARGS_LENGTH)
-      @logs = logs || []
-      @agents = normalize_agents(agents)
-      @include_tool_results = include_tool_results
-      @include_thinking = include_thinking
-      @max_result_length = max_result_length
-      @max_args_length = max_args_length
-    end
-
-    # Build the transcript
-    #
-    # @return [String] Formatted transcript
-    def build
-      @logs
-        .filter_map { |event| format_event(event) }
-        .join("\n\n")
-    end
-
-    private
-
-    # Normalize agent filter to array of symbols
-    #
-    # @param agents [Array, Symbol, String, nil] Agent filter input
-    # @return [Array<Symbol>, nil] Normalized agent list or nil for all
-    def normalize_agents(agents)
-      return if agents.nil? || (agents.is_a?(Array) && agents.empty?)
-
-      Array(agents).map(&:to_sym)
-    end
-
-    # Check if event passes agent filter
-    #
-    # @param event [Hash] Log event
-    # @return [Boolean] True if event should be included
-    def passes_agent_filter?(event)
-      return true if @agents.nil?
-
-      agent = event[:agent] || event["agent"]
-      return true if agent.nil? # Include events without agent (like swarm_start)
-
-      @agents.include?(agent.to_sym)
-    end
-
-    # Format a single event into transcript text
-    #
-    # @param event [Hash] Log event
-    # @return [String, nil] Formatted text or nil to skip
-    def format_event(event)
-      return unless passes_agent_filter?(event)
-
-      type = event[:type] || event["type"]
-
-      case type
-      when "user_prompt"
-        format_user_prompt(event)
-      when "agent_step"
-        format_agent_step(event)
-      when "agent_stop"
-        format_agent_stop(event)
-      when "tool_call"
-        format_tool_call(event)
-      when "tool_result"
-        format_tool_result(event)
-      when "pre_delegation", "delegation_start"
-        format_delegation_start(event)
-      when "post_delegation", "delegation_complete"
-        format_delegation_complete(event)
-      end
-    end
-
-    # Format user_prompt event
-    #
-    # @param event [Hash] Event data
-    # @return [String, nil] Formatted text
-    def format_user_prompt(event)
-      prompt = event[:prompt] || event["prompt"]
-      return if prompt.nil? || prompt.to_s.strip.empty?
-
-      agent = event[:agent] || event["agent"]
-      source = event[:source] || event["source"] || "user"
-
-      # Show source if it's a delegation or system message
-      prefix = case source.to_s
-      when "delegation"
-        "DELEGATION REQUEST"
-      when "system"
-        "SYSTEM"
-      else
-        "USER"
-      end
-
-      if agent && source.to_s != "user"
-        "#{prefix} → [#{agent}]: #{prompt}"
-      else
-        "#{prefix}: #{prompt}"
-      end
-    end
-
-    # Format agent_step event (intermediate response with tool calls)
-    #
-    # @param event [Hash] Event data
-    # @return [String, nil] Formatted text
-    def format_agent_step(event)
-      return unless @include_thinking
-
-      content = event[:content] || event["content"]
-      return if content.nil? || content.to_s.strip.empty?
-
-      agent = event[:agent] || event["agent"]
-      "AGENT [#{agent}] (thinking): #{content}"
-    end
-
-    # Format agent_stop event (final response)
-    #
-    # @param event [Hash] Event data
-    # @return [String, nil] Formatted text
-    def format_agent_stop(event)
-      content = event[:content] || event["content"]
-      return if content.nil? || content.to_s.strip.empty?
-
-      agent = event[:agent] || event["agent"]
-      "AGENT [#{agent}]: #{content}"
-    end
-
-    # Format tool_call event
-    #
-    # @param event [Hash] Event data
-    # @return [String] Formatted text
-    def format_tool_call(event)
-      tool = event[:tool] || event["tool"] || event[:tool_name] || event["tool_name"]
-      agent = event[:agent] || event["agent"]
-      arguments = event[:arguments] || event["arguments"]
-
-      args_str = format_arguments(arguments)
-      "TOOL [#{agent}] → #{tool}(#{args_str})"
-    end
-
-    # Format tool_result event
-    #
-    # @param event [Hash] Event data
-    # @return [String, nil] Formatted text
-    def format_tool_result(event)
-      return unless @include_tool_results
-
-      tool = event[:tool] || event["tool"] || event[:tool_name] || event["tool_name"]
-      result = event[:result] || event["result"]
-      # Use key existence check since false || nil would lose the false value
-      success = event.key?(:success) ? event[:success] : event["success"]
-
-      # Handle RubyLLM::ToolResult objects
-      result_content = if result.respond_to?(:content)
-        result.content
-      else
-        result.to_s
-      end
-
-      truncated = truncate(result_content, @max_result_length)
-
-      status = success == false ? " [FAILED]" : ""
-      "RESULT [#{tool}]#{status}: #{truncated}"
-    end
-
-    # Format delegation_start event
-    #
-    # @param event [Hash] Event data
-    # @return [String, nil] Formatted text
-    def format_delegation_start(event)
-      from = event[:from_agent] || event["from_agent"] || event[:agent] || event["agent"]
-      to = event[:to_agent] || event["to_agent"]
-      task = event[:task] || event["task"] || event[:message] || event["message"]
-
-      return unless to
-
-      task_preview = truncate(task.to_s, 200)
-      "DELEGATE: #{from} → #{to}: #{task_preview}"
-    end
-
-    # Format delegation_complete event
-    #
-    # @param event [Hash] Event data
-    # @return [String, nil] Formatted text
-    def format_delegation_complete(event)
-      from = event[:from_agent] || event["from_agent"] || event[:agent] || event["agent"]
-      to = event[:to_agent] || event["to_agent"]
-
-      return unless to
-
-      "DELEGATE COMPLETE: #{to} → #{from}"
-    end
-
-    # Format tool arguments for display
-    #
-    # @param arguments [Hash, String, nil] Tool arguments
-    # @return [String] Formatted arguments
-    def format_arguments(arguments)
-      return "{}" if arguments.nil?
-
-      str = arguments.is_a?(String) ? arguments : arguments.to_json
-      truncate(str, @max_args_length)
-    end
-
-    # Truncate text to maximum length with ellipsis
-    #
-    # @param text [String, nil] Text to truncate
-    # @param max [Integer] Maximum length
-    # @return [String] Truncated text
-    def truncate(text, max)
-      return "" if text.nil?
-
-      str = text.to_s
-      return str if str.length <= max
-
-      "#{str[0...max]}..."
-    end
-  end
-end

data/lib/swarm_sdk/utils.rb

@@ -1,68 +0,0 @@
-# frozen_string_literal: true
-
-module SwarmSDK
-  # Shared utility methods for SwarmSDK
-  module Utils
-    class << self
-      # Recursively convert all hash keys to symbols
-      #
-      # Handles nested hashes and arrays containing hashes.
-      #
-      # @param obj [Object] Object to symbolize (Hash, Array, or other)
-      # @return [Object] Object with symbolized keys (if applicable)
-      #
-      # @example
-      #   Utils.symbolize_keys({ "name" => "test", "config" => { "key" => "value" } })
-      #   # => { name: "test", config: { key: "value" } }
-      def symbolize_keys(obj)
-        case obj
-        when Hash
-          obj.transform_keys(&:to_sym).transform_values { |v| symbolize_keys(v) }
-        when Array
-          obj.map { |item| symbolize_keys(item) }
-        else
-          obj
-        end
-      end
-
-      # Recursively convert all hash keys to strings
-      #
-      # Handles nested hashes and arrays containing hashes.
-      #
-      # @param obj [Object] Object to stringify (Hash, Array, or other)
-      # @return [Object] Object with stringified keys (if applicable)
-      #
-      # @example
-      #   Utils.stringify_keys({ name: "test", config: { key: "value" } })
-      #   # => { "name" => "test", "config" => { "key" => "value" } }
-      def stringify_keys(obj)
-        case obj
-        when Hash
-          obj.transform_keys(&:to_s).transform_values { |v| stringify_keys(v) }
-        when Array
-          obj.map { |item| stringify_keys(item) }
-        else
-          obj
-        end
-      end
-
-      # Convert hash to YAML string
-      #
-      # Converts a Ruby hash to a YAML string. Useful for creating inline
-      # swarm definitions from hash configurations.
-      #
-      # @param hash [Hash] Hash to convert
-      # @return [String] YAML string representation
-      #
-      # @example
-      #   config = { version: 2, swarm: { name: "Test" } }
-      #   Utils.hash_to_yaml(config)
-      #   # => "---\nversion: 2\nswarm:\n  name: Test\n"
-      def hash_to_yaml(hash)
-        # Convert symbols to strings for valid YAML
-        stringified = stringify_keys(hash)
-        stringified.to_yaml
-      end
-    end
-  end
-end

data/lib/swarm_sdk/validation_result.rb

@@ -1,33 +0,0 @@
-# frozen_string_literal: true
-
-module SwarmSDK
-  # Internal result object for validation phase during snapshot restore
-  #
-  # Used during restore to track which agents can be restored and which
-  # need to be skipped due to configuration mismatches.
-  #
-  # @api private
-  class ValidationResult
-    attr_reader :warnings,
-      :skipped_agents,
-      :restorable_agents,
-      :skipped_delegations,
-      :restorable_delegations
-
-    # Initialize validation result
-    #
-    # @param warnings [Array<Hash>] Warning messages with details
-    # @param skipped_agents [Array<Symbol>] Names of agents that can't be restored
-    # @param restorable_agents [Array<Symbol>] Names of agents that can be restored
-    # @param skipped_delegations [Array<String>] Names of delegations that can't be restored
-    # @param restorable_delegations [Array<String>] Names of delegations that can be restored
-    def initialize(warnings:, skipped_agents:, restorable_agents:,
-      skipped_delegations:, restorable_delegations:)
-      @warnings = warnings
-      @skipped_agents = skipped_agents
-      @restorable_agents = restorable_agents
-      @skipped_delegations = skipped_delegations
-      @restorable_delegations = restorable_delegations
-    end
-  end
-end

data/lib/swarm_sdk/version.rb

@@ -1,5 +0,0 @@
-# frozen_string_literal: true
-
-module SwarmSDK
-  VERSION = "2.7.14"
-end

data/lib/swarm_sdk/workflow/agent_config.rb

@@ -1,95 +0,0 @@
-# frozen_string_literal: true
-
-module SwarmSDK
-  class Workflow
-    # AgentConfig provides fluent API for configuring agents within a node
-    #
-    # This class enables the chainable syntax:
-    #   agent(:backend).delegates_to(:tester, :database)
-    #   agent(:backend, reset_context: false)  # Preserve context across nodes
-    #   agent(:backend).tools(:Read, :Edit)    # Override tools for this node
-    #
-    # @example Basic delegation
-    #   agent(:backend).delegates_to(:tester)
-    #
-    # @example No delegation (solo agent)
-    #   agent(:planner)
-    #
-    # @example Preserve agent context
-    #   agent(:architect, reset_context: false)
-    #
-    # @example Override tools for this node
-    #   agent(:backend).tools(:Read, :Think)
-    #
-    # @example Combine delegation and tool override
-    #   agent(:backend).delegates_to(:tester).tools(:Read, :Edit, :Write)
-    class AgentConfig
-      attr_reader :agent_name
-
-      def initialize(agent_name, node_builder, reset_context: true)
-        @agent_name = agent_name
-        @node_builder = node_builder
-        @delegates_to = []
-        @reset_context = reset_context
-        @tools = nil # nil means use global agent definition tools
-        @finalized = false
-      end
-
-      # Set delegation targets for this agent
-      #
-      # Supports multiple formats for flexibility:
-      # - Array: delegates_to(:frontend, :backend)
-      # - Hash: delegates_to(frontend: "AskFrontend", backend: "GetBackend")
-      #
-      # @param agent_names_and_options [Array<Symbol, Hash>] Names and/or hash with custom tool names
-      # @return [self] For method chaining
-      def delegates_to(*agent_names_and_options)
-        # Parse delegation configs (same logic as Agent::Builder)
-        @delegates_to = []
-        agent_names_and_options.each do |item|
-          case item
-          when Symbol, String
-            @delegates_to << { agent: item.to_sym, tool_name: nil }
-          when Hash
-            item.each do |agent, tool_name|
-              @delegates_to << { agent: agent.to_sym, tool_name: tool_name }
-            end
-          end
-        end
-
-        update_registration
-        self
-      end
-
-      # Override tools for this agent in this node
-      #
-      # @param tool_names [Array<Symbol>] Tool names to use (overrides global agent definition)
-      # @return [self] For method chaining
-      #
-      # @example
-      #   agent(:backend).tools(:Read, :Edit)
-      def tools(*tool_names)
-        @tools = tool_names.map(&:to_sym)
-        update_registration
-        self
-      end
-
-      # Update agent registration (called after each fluent method)
-      #
-      # Always updates the registration with current state.
-      # This allows chaining: .delegates_to(...).tools(...)
-      #
-      # @return [void]
-      def update_registration
-        @node_builder.register_agent(@agent_name, @delegates_to, @reset_context, @tools)
-      end
-
-      # Finalize agent configuration (backward compatibility)
-      #
-      # @return [void]
-      def finalize
-        update_registration
-      end
-    end
-  end
-end