claude_swarm 1.0.1 → 1.0.2

data/lib/swarm_sdk/claude_code_agent_adapter.rb

@@ -0,0 +1,205 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  # Adapter for converting Claude Code agent markdown files to SwarmSDK format
+  #
+  # Claude Code agent files use a different syntax and conventions than SwarmSDK:
+  # - Tools are comma-separated strings instead of arrays
+  # - Model shortcuts like 'sonnet', 'opus', 'haiku' instead of full model IDs
+  # - Tool permissions like 'Write(src/**)' instead of SwarmSDK's permission system
+  # - Required 'name' field in frontmatter
+  #
+  # This adapter:
+  # - Detects Claude Code format by checking frontmatter markers
+  # - Converts tools from comma-separated strings to arrays
+  # - Maps model shortcuts to canonical model IDs
+  # - Strips unsupported tool permission syntax with warnings
+  # - Sets coding_agent: true by default
+  # - Warns about unsupported fields
+  #
+  # @example Parse a Claude Code agent file
+  #   content = File.read('.claude/agents/reviewer.md')
+  #   config = ClaudeCodeAgentAdapter.parse(content, :reviewer)
+  #   agent = Agent::Definition.new(:reviewer, config)
+  #
+  class ClaudeCodeAgentAdapter
+    # Fields supported in Claude Code agent frontmatter
+    SUPPORTED_FIELDS = ["name", "description", "tools", "model"].freeze
+
+    # SwarmSDK documentation URL for reference
+    SWARM_SDK_DOCS_URL = "https://github.com/parruda/claude-swarm/blob/main/docs/v2/README.md"
+
+    # Pattern to detect tool permission syntax like Write(src/**)
+    TOOL_PERMISSION_PATTERN = /^([A-Za-z_]+)\([^)]+\)$/
+
+    class << self
+      # Detect if content appears to be in Claude Code agent format
+      #
+      # Detection is based on tools field type:
+      # - Claude Code: tools is a comma-separated string (e.g., "Read, Write, Bash")
+      # - SwarmSDK: tools is an array (e.g., [Read, Write, Bash])
+      #
+      # Note: The 'name' field alone is not sufficient since SwarmSDK also supports it
+      #
+      # @param content [String] Markdown content with YAML frontmatter
+      # @return [Boolean] true if content appears to be Claude Code format
+      def claude_code_format?(content)
+        return false unless content =~ /\A---\s*\n(.*?)\n---\s*\n/m
+
+        frontmatter_yaml = Regexp.last_match(1)
+        frontmatter = YAML.safe_load(frontmatter_yaml, permitted_classes: [Symbol], aliases: true)
+
+        return false unless frontmatter.is_a?(Hash)
+
+        # Only detect as Claude Code if tools field is a comma-separated string
+        # This is the most reliable indicator since SwarmSDK always uses arrays
+        frontmatter.key?("tools") && frontmatter["tools"].is_a?(String)
+      rescue Psych::SyntaxError
+        false
+      end
+
+      # Parse Claude Code agent markdown and convert to SwarmSDK format
+      #
+      # @param content [String] Markdown content with YAML frontmatter
+      # @param agent_name [Symbol, String] Name of the agent
+      # @param inherit_model [String, nil] Model to use when frontmatter has 'inherit'
+      # @return [Hash] Configuration hash suitable for Agent::Definition.new
+      # @raise [ConfigurationError] if content format is invalid
+      def parse(content, agent_name, inherit_model: nil)
+        new(inherit_model: inherit_model).parse(content, agent_name)
+      end
+    end
+
+    # Initialize adapter with optional context
+    #
+    # @param inherit_model [String, nil] Model to use when frontmatter has 'inherit'
+    def initialize(inherit_model: nil)
+      @inherit_model = inherit_model
+      @warnings = []
+    end
+
+    # Parse Claude Code agent content
+    #
+    # @param content [String] Markdown content with YAML frontmatter
+    # @param agent_name [Symbol, String] Name of the agent
+    # @return [Hash] Configuration hash for Agent::Definition
+    # @raise [ConfigurationError] if format is invalid
+    def parse(content, agent_name)
+      unless content =~ /\A---\s*\n(.*?)\n---\s*\n(.*)\z/m
+        raise ConfigurationError, "Invalid Claude Code agent format. Expected YAML frontmatter followed by prompt content."
+      end
+
+      frontmatter_yaml = Regexp.last_match(1)
+      prompt_content = Regexp.last_match(2).strip
+
+      frontmatter = YAML.safe_load(frontmatter_yaml, permitted_classes: [Symbol], aliases: true)
+
+      unless frontmatter.is_a?(Hash)
+        raise ConfigurationError, "Invalid frontmatter format in Claude Code agent file"
+      end
+
+      config = build_config(frontmatter, prompt_content, agent_name)
+      emit_warnings(agent_name)
+      config
+    end
+
+    private
+
+    # Build SwarmSDK configuration from Claude Code frontmatter
+    def build_config(frontmatter, prompt_content, agent_name)
+      warn_unknown_fields(frontmatter)
+
+      config = {
+        description: frontmatter["description"],
+        system_prompt: prompt_content,
+        coding_agent: true, # Default for Claude Code agents
+      }
+
+      # Parse tools if present
+      if frontmatter["tools"]
+        config[:tools] = parse_tools(frontmatter["tools"])
+      end
+
+      # Parse model if present
+      if frontmatter["model"]
+        config[:model] = resolve_model(frontmatter["model"])
+      end
+
+      config
+    end
+
+    # Parse tools field - handles both comma-separated string and array
+    #
+    # @param tools_field [String, Array] Tools from frontmatter
+    # @return [Array<String>] Array of tool names
+    def parse_tools(tools_field)
+      tools_array = if tools_field.is_a?(String)
+        tools_field.split(",").map(&:strip)
+      else
+        Array(tools_field).map(&:to_s)
+      end
+
+      # Clean tool permissions and collect warnings
+      tools_array.map { |tool| clean_tool_permissions(tool) }.compact
+    end
+
+    # Strip tool permission syntax and warn if detected
+    #
+    # @param tool_string [String] Tool name, possibly with permissions like 'Write(src/**)'
+    # @return [String, nil] Clean tool name, or nil if invalid
+    def clean_tool_permissions(tool_string)
+      if tool_string =~ TOOL_PERMISSION_PATTERN
+        tool_name = Regexp.last_match(1)
+        @warnings << "Tool permission syntax '#{tool_string}' detected in agent file. SwarmSDK supports permissions but uses different syntax. Using '#{tool_name}' without restrictions for now. See SwarmSDK documentation for permission configuration: #{SWARM_SDK_DOCS_URL}"
+        tool_name
+      else
+        tool_string
+      end
+    end
+
+    # Resolve model shortcuts to canonical model IDs
+    #
+    # Uses SwarmSDK::Models.resolve_alias to map shortcuts like 'sonnet'
+    # to the latest model IDs from model_aliases.json.
+    #
+    # @param model_field [String] Model from frontmatter
+    # @return [String, Symbol] Canonical model ID or :inherit symbol
+    def resolve_model(model_field)
+      model_str = model_field.to_s.strip
+
+      # Handle 'inherit' keyword
+      return :inherit if model_str == "inherit"
+
+      # Resolve using SwarmSDK model aliases
+      # This maps 'sonnet' → 'claude-sonnet-4-5-20250929', etc.
+      SwarmSDK::Models.resolve_alias(model_str)
+    end
+
+    # Warn about unknown frontmatter fields
+    def warn_unknown_fields(frontmatter)
+      unknown_fields = frontmatter.keys - SUPPORTED_FIELDS
+
+      unknown_fields.each do |field|
+        @warnings << case field
+        when "hooks"
+          "Hooks configuration detected in agent frontmatter. SwarmSDK handles hooks at the swarm level. See: #{SWARM_SDK_DOCS_URL}"
+        else
+          "Unknown field '#{field}' in Claude Code agent file. Ignoring. Supported fields: #{SUPPORTED_FIELDS.join(", ")}"
+        end
+      end
+    end
+
+    # Emit all collected warnings via LogCollector
+    def emit_warnings(agent_name)
+      return if @warnings.empty?
+
+      @warnings.each do |warning|
+        LogCollector.emit(
+          type: "claude_code_conversion_warning",
+          agent: agent_name,
+          message: warning,
+        )
+      end
+    end
+  end
+end

data/lib/swarm_sdk/configuration.rb

@@ -0,0 +1,296 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  class Configuration
+    ENV_VAR_WITH_DEFAULT_PATTERN = /\$\{([^:}]+)(:=([^}]*))?\}/
+
+    attr_reader :config_path, :swarm_name, :lead_agent, :agents, :all_agents_config, :swarm_hooks, :all_agents_hooks, :scratchpad_enabled
+
+    class << self
+      def load(path)
+        new(path).tap(&:load_and_validate)
+      end
+    end
+
+    def initialize(config_path)
+      @config_path = Pathname.new(config_path).expand_path
+      @config_dir = @config_path.dirname
+      @agents = {}
+      @all_agents_config = {} # Settings applied to all agents
+      @swarm_hooks = {} # Swarm-level hooks (swarm_start, swarm_stop)
+      @all_agents_hooks = {} # Hooks applied to all agents
+    end
+
+    def load_and_validate
+      @config = YAML.load_file(@config_path, aliases: true)
+
+      unless @config.is_a?(Hash)
+        raise ConfigurationError, "Invalid YAML syntax: configuration must be a Hash"
+      end
+
+      @config = Utils.symbolize_keys(@config)
+      interpolate_env_vars!(@config)
+      validate_version
+      load_all_agents_config
+      load_hooks_config
+      validate_swarm
+      load_agents
+      detect_circular_dependencies
+      self
+    rescue Errno::ENOENT
+      raise ConfigurationError, "Configuration file not found: #{@config_path}"
+    rescue Psych::SyntaxError => e
+      raise ConfigurationError, "Invalid YAML syntax: #{e.message}"
+    end
+
+    def agent_names
+      @agents.keys
+    end
+
+    def connections_for(agent_name)
+      @agents[agent_name]&.delegates_to || []
+    end
+
+    # Convert configuration to Swarm instance using Ruby API
+    #
+    # This method bridges YAML configuration to the Ruby API, making YAML
+    # a thin convenience layer over the programmatic interface.
+    #
+    # @return [Swarm] Configured swarm instance
+    def to_swarm
+      swarm = Swarm.new(
+        name: @swarm_name,
+        global_concurrency: Swarm::DEFAULT_GLOBAL_CONCURRENCY,
+        default_local_concurrency: Swarm::DEFAULT_LOCAL_CONCURRENCY,
+        scratchpad_enabled: @scratchpad_enabled,
+      )
+
+      # Add all agents - pass definitions directly
+      @agents.each do |_name, agent_def|
+        swarm.add_agent(agent_def)
+      end
+
+      # Set lead agent
+      swarm.lead = @lead_agent
+
+      swarm
+    end
+
+    private
+
+    def interpolate_env_vars!(obj)
+      case obj
+      when String
+        interpolate_env_string(obj)
+      when Hash
+        obj.transform_values! { |v| interpolate_env_vars!(v) }
+      when Array
+        obj.map! { |v| interpolate_env_vars!(v) }
+      else
+        obj
+      end
+    end
+
+    def interpolate_env_string(str)
+      str.gsub(ENV_VAR_WITH_DEFAULT_PATTERN) do |_match|
+        env_var = Regexp.last_match(1)
+        has_default = Regexp.last_match(2)
+        default_value = Regexp.last_match(3)
+
+        if ENV.key?(env_var)
+          ENV[env_var]
+        elsif has_default
+          default_value || ""
+        else
+          raise ConfigurationError, "Environment variable '#{env_var}' is not set"
+        end
+      end
+    end
+
+    def validate_version
+      version = @config[:version]
+      raise ConfigurationError, "Missing 'version' field in configuration" unless version
+      raise ConfigurationError, "SwarmSDK requires version: 2 configuration. Got version: #{version}" unless version == 2
+    end
+
+    def load_all_agents_config
+      return unless @config[:swarm]
+
+      @all_agents_config = @config[:swarm][:all_agents] || {}
+
+      # Convert disable_default_tools array elements to symbols
+      if @all_agents_config[:disable_default_tools].is_a?(Array)
+        @all_agents_config[:disable_default_tools] = @all_agents_config[:disable_default_tools].map(&:to_sym)
+      end
+    end
+
+    def load_hooks_config
+      return unless @config[:swarm]
+
+      # Load swarm-level hooks (only swarm_start, swarm_stop allowed)
+      @swarm_hooks = Utils.symbolize_keys(@config[:swarm][:hooks] || {})
+
+      # Load all_agents hooks (applied as swarm defaults)
+      if @config[:swarm][:all_agents]
+        @all_agents_hooks = Utils.symbolize_keys(@config[:swarm][:all_agents][:hooks] || {})
+      end
+    end
+
+    def validate_swarm
+      raise ConfigurationError, "Missing 'swarm' field in configuration" unless @config[:swarm]
+
+      swarm = @config[:swarm]
+      raise ConfigurationError, "Missing 'name' field in swarm configuration" unless swarm[:name]
+      raise ConfigurationError, "Missing 'agents' field in swarm configuration" unless swarm[:agents]
+      raise ConfigurationError, "Missing 'lead' field in swarm configuration" unless swarm[:lead]
+      raise ConfigurationError, "No agents defined" if swarm[:agents].empty?
+
+      @swarm_name = swarm[:name]
+      @lead_agent = swarm[:lead].to_sym # Convert to symbol for consistency
+      @scratchpad_enabled = swarm[:use_scratchpad].nil? ? true : swarm[:use_scratchpad] # Default: enabled
+    end
+
+    def load_agents
+      swarm_agents = @config[:swarm][:agents]
+
+      swarm_agents.each do |name, agent_config|
+        # Support three formats:
+        # 1. String: assistant: "agents/assistant.md" (file path)
+        # 2. Hash with agent_file: assistant: { agent_file: "..." }
+        # 3. Hash with inline definition: assistant: { description: "...", model: "..." }
+
+        if agent_config.is_a?(String)
+          # Format 1: Direct file path as string
+          file_path = agent_config
+          merged_config = merge_all_agents_config({})
+          @agents[name] = load_agent_from_file(name, file_path, merged_config)
+        else
+          # Format 2 or 3: Hash configuration
+          agent_config ||= {}
+
+          # Merge all_agents_config into agent config
+          # Agent-specific config overrides all_agents config
+          merged_config = merge_all_agents_config(agent_config)
+
+          @agents[name] = if agent_config[:agent_file]
+            # Format 2: Hash with agent_file key
+            load_agent_from_file(name, agent_config[:agent_file], merged_config)
+          else
+            # Format 3: Inline definition
+            Agent::Definition.new(name, merged_config)
+          end
+        end
+      end
+
+      unless @agents.key?(@lead_agent)
+        raise ConfigurationError, "Lead agent '#{@lead_agent}' not found in agents"
+      end
+    end
+
+    # Merge all_agents config with agent-specific config
+    # Agent config takes precedence over all_agents config
+    #
+    # Merge strategy:
+    # - Arrays (tools, delegates_to): Concatenate
+    # - Hashes (parameters, headers): Merge (agent values override)
+    # - Scalars (model, provider, base_url, timeout, coding_agent): Agent overrides
+    #
+    # @param agent_config [Hash] Agent-specific configuration
+    # @return [Hash] Merged configuration
+    def merge_all_agents_config(agent_config)
+      merged = @all_agents_config.dup
+
+      # For arrays, concatenate
+      # For hashes, merge (agent values override)
+      # For scalars, agent value overrides
+      agent_config.each do |key, value|
+        case key
+        when :tools
+          # Concatenate tools: all_agents.tools + agent.tools
+          merged[:tools] = Array(merged[:tools]) + Array(value)
+        when :delegates_to
+          # Concatenate delegates_to
+          merged[:delegates_to] = Array(merged[:delegates_to]) + Array(value)
+        when :parameters
+          # Merge parameters: all_agents.parameters + agent.parameters
+          # Agent values override all_agents values for same keys
+          merged[:parameters] = (merged[:parameters] || {}).merge(value || {})
+        when :headers
+          # Merge headers: all_agents.headers + agent.headers
+          # Agent values override all_agents values for same keys
+          merged[:headers] = (merged[:headers] || {}).merge(value || {})
+        when :disable_default_tools
+          # Convert array elements to symbols if it's an array
+          merged[key] = value.is_a?(Array) ? value.map(&:to_sym) : value
+        else
+          # For everything else (model, provider, base_url, timeout, coding_agent, etc.),
+          # agent value overrides all_agents value
+          merged[key] = value
+        end
+      end
+
+      # Pass all_agents permissions as default_permissions for backward compat with AgentDefinition
+      if @all_agents_config[:permissions]
+        merged[:default_permissions] = @all_agents_config[:permissions]
+      end
+
+      merged
+    end
+
+    def load_agent_from_file(name, file_path, merged_config)
+      agent_file_path = resolve_agent_file_path(file_path)
+
+      unless File.exist?(agent_file_path)
+        raise ConfigurationError, "Agent file not found: #{agent_file_path}"
+      end
+
+      content = File.read(agent_file_path)
+      # Parse markdown and merge with YAML config
+      agent_def_from_file = MarkdownParser.parse(content, name)
+
+      # Merge: YAML config overrides markdown file (YAML takes precedence)
+      # This allows YAML to override any settings from the markdown file
+      final_config = agent_def_from_file.to_h.compact.merge(merged_config.compact)
+
+      Agent::Definition.new(name, final_config)
+    rescue StandardError => e
+      raise ConfigurationError, "Error loading agent '#{name}' from file '#{file_path}': #{e.message}"
+    end
+
+    def resolve_agent_file_path(file_path)
+      return file_path if Pathname.new(file_path).absolute?
+
+      @config_dir.join(file_path).to_s
+    end
+
+    def detect_circular_dependencies
+      @agents.each_key do |agent_name|
+        visited = Set.new
+        path = []
+        detect_cycle_from(agent_name, visited, path)
+      end
+    end
+
+    def detect_cycle_from(agent_name, visited, path)
+      return if visited.include?(agent_name)
+
+      if path.include?(agent_name)
+        cycle_start = path.index(agent_name)
+        cycle = path[cycle_start..] + [agent_name]
+        raise CircularDependencyError, "Circular dependency detected: #{cycle.join(" -> ")}"
+      end
+
+      path.push(agent_name)
+      connections_for(agent_name).each do |connection|
+        connection_sym = connection.to_sym # Convert to symbol for lookup
+        unless @agents.key?(connection_sym)
+          raise ConfigurationError, "Agent '#{agent_name}' has connection to unknown agent '#{connection}'"
+        end
+
+        detect_cycle_from(connection_sym, visited, path)
+      end
+      path.pop
+      visited.add(agent_name)
+    end
+  end
+end

data/lib/swarm_sdk/context_compactor/metrics.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  class ContextCompactor
+    # Metrics tracks compression statistics
+    #
+    # Provides detailed information about the compression operation:
+    # - Message counts (before/after)
+    # - Token counts (before/after)
+    # - Compression ratio
+    # - Time taken
+    # - Summary of changes
+    #
+    # ## Usage
+    #
+    #   metrics = agent.compact_context
+    #   puts metrics.summary
+    #   puts "Compressed from #{metrics.original_tokens} to #{metrics.compressed_tokens} tokens"
+    #   puts "Compression ratio: #{(metrics.compression_ratio * 100).round(1)}%"
+    #
+    class Metrics
+      attr_reader :original_messages, :compressed_messages, :time_taken
+
+      # Initialize metrics from compression operation
+      #
+      # @param original_messages [Array<RubyLLM::Message>] Messages before compression
+      # @param compressed_messages [Array<RubyLLM::Message>] Messages after compression
+      # @param time_taken [Float] Time taken in seconds
+      def initialize(original_messages:, compressed_messages:, time_taken:)
+        @original_messages = original_messages
+        @compressed_messages = compressed_messages
+        @time_taken = time_taken
+      end
+
+      # Number of messages before compression
+      #
+      # @return [Integer] Original message count
+      def original_message_count
+        @original_messages.size
+      end
+
+      # Number of messages after compression
+      #
+      # @return [Integer] Compressed message count
+      def compressed_message_count
+        @compressed_messages.size
+      end
+
+      # Number of messages removed
+      #
+      # @return [Integer] Messages removed
+      def messages_removed
+        original_message_count - compressed_message_count
+      end
+
+      # Number of checkpoint summary messages created
+      #
+      # @return [Integer] Checkpoint messages
+      def messages_summarized
+        @compressed_messages.count do |msg|
+          msg.role == :system && msg.content.to_s.include?("CONVERSATION CHECKPOINT")
+        end
+      end
+
+      # Estimated tokens before compression
+      #
+      # @return [Integer] Original token count
+      def original_tokens
+        @original_tokens ||= TokenCounter.estimate_messages(@original_messages)
+      end
+
+      # Estimated tokens after compression
+      #
+      # @return [Integer] Compressed token count
+      def compressed_tokens
+        @compressed_tokens ||= TokenCounter.estimate_messages(@compressed_messages)
+      end
+
+      # Number of tokens removed
+      #
+      # @return [Integer] Tokens removed
+      def tokens_removed
+        original_tokens - compressed_tokens
+      end
+
+      # Compression ratio (compressed / original)
+      #
+      # @return [Float] Ratio between 0.0 and 1.0
+      def compression_ratio
+        return 0.0 if original_tokens.zero?
+
+        compressed_tokens.to_f / original_tokens
+      end
+
+      # Compression factor (original / compressed)
+      #
+      # e.g., 5.0 means compressed to 1/5th of original size
+      #
+      # @return [Float] Compression factor
+      def compression_factor
+        return 0.0 if compressed_tokens.zero?
+
+        original_tokens.to_f / compressed_tokens
+      end
+
+      # Compression percentage
+      #
+      # @return [Float] Percentage of original size (0-100)
+      def compression_percentage
+        (compression_ratio * 100).round(2)
+      end
+
+      # Generate a human-readable summary
+      #
+      # @return [String] Summary text
+      def summary
+        <<~SUMMARY
+          Context Compression Results:
+          - Messages: #{original_message_count} → #{compressed_message_count} (-#{messages_removed})
+          - Estimated tokens: #{original_tokens} → #{compressed_tokens} (-#{tokens_removed})
+          - Compression ratio: #{compression_factor.round(1)}:1 (#{compression_percentage}%)
+          - Checkpoints created: #{messages_summarized}
+          - Time taken: #{time_taken.round(3)}s
+        SUMMARY
+      end
+
+      # Convert metrics to hash for logging
+      #
+      # @return [Hash] Metrics as hash
+      def to_h
+        {
+          original_message_count: original_message_count,
+          compressed_message_count: compressed_message_count,
+          messages_removed: messages_removed,
+          messages_summarized: messages_summarized,
+          original_tokens: original_tokens,
+          compressed_tokens: compressed_tokens,
+          tokens_removed: tokens_removed,
+          compression_ratio: compression_ratio.round(4),
+          compression_factor: compression_factor.round(2),
+          compression_percentage: compression_percentage,
+          time_taken: time_taken.round(3),
+        }
+      end
+    end
+  end
+end