swarm_sdk 2.0.0.pre.2

data/lib/swarm_sdk/tools/write.rb

@@ -0,0 +1,117 @@
+# 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 < RubyLLM::Tool
+      include PathResolver
+
+      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()
+        @agent_name = agent_name.to_sym
+        @directory = File.expand_path(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
+
+      private
+
+      # Helper methods
+      def validation_error(message)
+        "<tool_use_error>InputValidationError: #{message}</tool_use_error>"
+      end
+
+      def error(message)
+        "Error: #{message}"
+      end
+    end
+  end
+end

data/lib/swarm_sdk/utils.rb

@@ -0,0 +1,50 @@
+# 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
+    end
+  end
+end

data/lib/swarm_sdk/version.rb

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

data/lib/swarm_sdk.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require "bundler"
+require "digest"
+require "English"
+require "erb"
+require "fileutils"
+require "json"
+require "logger"
+require "pathname"
+require "securerandom"
+require "set"
+require "yaml"
+
+require "async"
+require "async/semaphore"
+require "ruby_llm"
+require "ruby_llm/mcp"
+
+module SwarmSDK
+end
+
+require "zeitwerk"
+loader = Zeitwerk::Loader.new
+loader.push_dir("#{__dir__}/swarm_sdk", namespace: SwarmSDK)
+loader.inflector.inflect(
+  "cli" => "CLI",
+)
+loader.setup
+
+# Load custom providers explicitly (Zeitwerk doesn't eager load by default)
+require_relative "swarm_sdk/providers/openai_with_responses"
+
+module SwarmSDK
+  class Error < StandardError; end
+  class ConfigurationError < Error; end
+  class AgentNotFoundError < Error; end
+  class CircularDependencyError < Error; end
+  class ToolExecutionError < Error; end
+  class LLMError < Error; end
+  class StateError < Error; end
+
+  class << self
+    # Refresh RubyLLM model registry silently (without log output)
+    #
+    # By default, RubyLLM.models.refresh! outputs INFO level logs about
+    # fetching models from providers. This method temporarily raises the
+    # log level to suppress those messages, which is useful for CLI tools
+    # that want clean output.
+    #
+    # @example
+    #   SwarmSDK.refresh_models_silently
+    #
+    # @return [void]
+    def refresh_models_silently
+      original_level = RubyLLM.logger.level
+      RubyLLM.logger.level = Logger::ERROR
+
+      RubyLLM.models.refresh!
+    ensure
+      RubyLLM.logger.level = original_level
+    end
+
+    # Main entry point for DSL
+    def build(&block)
+      Swarm::Builder.build(&block)
+    end
+  end
+end

metadata

@@ -0,0 +1,169 @@
+--- !ruby/object:Gem::Specification
+name: swarm_sdk
+version: !ruby/object:Gem::Version
+  version: 2.0.0.pre.2
+platform: ruby
+authors:
+- Paulo Arruda
+bindir: exe
+cert_chain: []
+date: 2025-10-14 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: async
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: ruby_llm
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+- !ruby/object:Gem::Dependency
+  name: ruby_llm-mcp
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: zeitwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+description: |
+  SwarmSDK is a complete reimagining of Claude Swarm that runs all AI agents in a single process
+  using RubyLLM for LLM interactions. Define collaborative AI agents in simple Markdown files with
+  YAML frontmatter, and orchestrate them without the overhead of multiple processes or MCP
+  inter-process communication. Perfect for building lightweight, efficient AI agent teams with
+  specialized roles and capabilities.
+email:
+- parrudaj@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/swarm_sdk.rb
+- lib/swarm_sdk/agent/builder.rb
+- lib/swarm_sdk/agent/chat.rb
+- lib/swarm_sdk/agent/chat/context_tracker.rb
+- lib/swarm_sdk/agent/chat/hook_integration.rb
+- lib/swarm_sdk/agent/chat/logging_helpers.rb
+- lib/swarm_sdk/agent/chat/system_reminder_injector.rb
+- lib/swarm_sdk/agent/context.rb
+- lib/swarm_sdk/agent/definition.rb
+- lib/swarm_sdk/configuration.rb
+- lib/swarm_sdk/context_compactor.rb
+- lib/swarm_sdk/context_compactor/metrics.rb
+- lib/swarm_sdk/context_compactor/token_counter.rb
+- lib/swarm_sdk/hooks/adapter.rb
+- lib/swarm_sdk/hooks/context.rb
+- lib/swarm_sdk/hooks/definition.rb
+- lib/swarm_sdk/hooks/error.rb
+- lib/swarm_sdk/hooks/executor.rb
+- lib/swarm_sdk/hooks/registry.rb
+- lib/swarm_sdk/hooks/result.rb
+- lib/swarm_sdk/hooks/shell_executor.rb
+- lib/swarm_sdk/hooks/tool_call.rb
+- lib/swarm_sdk/hooks/tool_result.rb
+- lib/swarm_sdk/log_collector.rb
+- lib/swarm_sdk/log_stream.rb
+- lib/swarm_sdk/markdown_parser.rb
+- lib/swarm_sdk/permissions/config.rb
+- lib/swarm_sdk/permissions/error_formatter.rb
+- lib/swarm_sdk/permissions/path_matcher.rb
+- lib/swarm_sdk/permissions/validator.rb
+- lib/swarm_sdk/permissions_builder.rb
+- lib/swarm_sdk/prompts/base_system_prompt.md.erb
+- lib/swarm_sdk/providers/openai_with_responses.rb
+- lib/swarm_sdk/result.rb
+- lib/swarm_sdk/swarm.rb
+- lib/swarm_sdk/swarm/agent_initializer.rb
+- lib/swarm_sdk/swarm/all_agents_builder.rb
+- lib/swarm_sdk/swarm/builder.rb
+- lib/swarm_sdk/swarm/mcp_configurator.rb
+- lib/swarm_sdk/swarm/tool_configurator.rb
+- lib/swarm_sdk/tools/bash.rb
+- lib/swarm_sdk/tools/delegate.rb
+- lib/swarm_sdk/tools/document_converters/base_converter.rb
+- lib/swarm_sdk/tools/document_converters/docx_converter.rb
+- lib/swarm_sdk/tools/document_converters/pdf_converter.rb
+- lib/swarm_sdk/tools/document_converters/xlsx_converter.rb
+- lib/swarm_sdk/tools/edit.rb
+- lib/swarm_sdk/tools/glob.rb
+- lib/swarm_sdk/tools/grep.rb
+- lib/swarm_sdk/tools/image_extractors/docx_image_extractor.rb
+- lib/swarm_sdk/tools/image_extractors/pdf_image_extractor.rb
+- lib/swarm_sdk/tools/image_formats/tiff_builder.rb
+- lib/swarm_sdk/tools/multi_edit.rb
+- lib/swarm_sdk/tools/path_resolver.rb
+- lib/swarm_sdk/tools/read.rb
+- lib/swarm_sdk/tools/registry.rb
+- lib/swarm_sdk/tools/scratchpad_list.rb
+- lib/swarm_sdk/tools/scratchpad_read.rb
+- lib/swarm_sdk/tools/scratchpad_write.rb
+- lib/swarm_sdk/tools/stores/read_tracker.rb
+- lib/swarm_sdk/tools/stores/scratchpad.rb
+- lib/swarm_sdk/tools/stores/todo_manager.rb
+- lib/swarm_sdk/tools/todo_write.rb
+- lib/swarm_sdk/tools/write.rb
+- lib/swarm_sdk/utils.rb
+- lib/swarm_sdk/version.rb
+homepage: https://github.com/parruda/claude-swarm
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/parruda/claude-swarm
+  changelog_uri: https://github.com/parruda/claude-swarm/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: Lightweight multi-agent AI orchestration using RubyLLM
+test_files: []