swarm_sdk 2.7.13 → 3.0.0.alpha1

data/lib/swarm_sdk/claude_code_agent_adapter.rb

@@ -1,205 +0,0 @@
-# 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/concerns/cleanupable.rb

@@ -1,39 +0,0 @@
-# frozen_string_literal: true
-
-module SwarmSDK
-  module Concerns
-    # Shared cleanup functionality for Swarm and Workflow
-    #
-    # Both classes must have:
-    # - mcp_clients: Hash of MCP client arrays
-    # - delegation_instances_hash: Hash of delegation instances (via Snapshotable)
-    #
-    module Cleanupable
-      # Cleanup all MCP clients
-      #
-      # Stops all MCP client connections gracefully.
-      # Should be called when the swarm/workflow is no longer needed.
-      #
-      # @return [void]
-      def cleanup
-        # Check if there's anything to clean up
-        return if @mcp_clients.empty? && (!delegation_instances_hash || delegation_instances_hash.empty?)
-
-        # Stop MCP clients for all agents
-        @mcp_clients.each do |agent_name, clients|
-          clients.each do |client|
-            client.stop
-            RubyLLM.logger.debug("SwarmSDK: Stopped MCP client '#{client.name}' for agent #{agent_name}")
-          rescue StandardError => e
-            RubyLLM.logger.debug("SwarmSDK: Error stopping MCP client '#{client.name}': #{e.message}")
-          end
-        end
-
-        @mcp_clients.clear
-
-        # Clear delegation instances
-        delegation_instances_hash&.clear
-      end
-    end
-  end
-end

data/lib/swarm_sdk/concerns/snapshotable.rb

@@ -1,67 +0,0 @@
-# frozen_string_literal: true
-
-module SwarmSDK
-  module Concerns
-    # Shared snapshot and restore functionality for Swarm and Workflow
-    #
-    # Both classes must implement:
-    # - primary_agents: Returns hash of primary agent instances
-    # - delegation_instances_hash: Returns hash of delegation instances
-    # - agent_definitions: Returns hash of agent definitions
-    # - swarm_id: Returns the swarm/workflow ID
-    # - parent_swarm_id: Returns the parent ID (or nil)
-    # - name: Returns the swarm/workflow name
-    #
-    module Snapshotable
-      # Create snapshot of current conversation state
-      #
-      # Returns a Snapshot object containing:
-      # - All agent conversations (@messages arrays)
-      # - Agent context state (warnings, compression, TodoWrite tracking, skills)
-      # - Delegation instance conversations
-      # - Scratchpad contents (volatile shared storage)
-      # - Read tracking state (which files each agent has read with digests)
-      # - Memory read tracking state (which memory entries each agent has read with digests)
-      #
-      # @return [Snapshot] Snapshot object with convenient serialization methods
-      def snapshot
-        StateSnapshot.new(self).snapshot
-      end
-
-      # Restore conversation state from snapshot
-      #
-      # Accepts a Snapshot object, hash, or JSON string. Validates compatibility
-      # between snapshot and current configuration, restores agent conversations,
-      # context state, scratchpad, and read tracking.
-      #
-      # The swarm/workflow must be created with the SAME configuration (agent definitions,
-      # tools, prompts) as when the snapshot was created. Only conversation state
-      # is restored from the snapshot.
-      #
-      # @param snapshot [Snapshot, Hash, String] Snapshot object, hash, or JSON string
-      # @param preserve_system_prompts [Boolean] Use historical system prompts instead of current config (default: false)
-      # @return [RestoreResult] Result with warnings about skipped agents
-      def restore(snapshot, preserve_system_prompts: false)
-        StateRestorer.new(self, snapshot, preserve_system_prompts: preserve_system_prompts).restore
-      end
-
-      # Interface method: Get primary agent instances
-      #
-      # Must be implemented by including class.
-      #
-      # @return [Hash<Symbol, Agent::Chat>] Primary agent instances
-      def primary_agents
-        raise NotImplementedError, "#{self.class} must implement #primary_agents"
-      end
-
-      # Interface method: Get delegation instance hash
-      #
-      # Must be implemented by including class.
-      #
-      # @return [Hash<String, Agent::Chat>] Delegation instances with keys like "delegate@delegator"
-      def delegation_instances_hash
-        raise NotImplementedError, "#{self.class} must implement #delegation_instances_hash"
-      end
-    end
-  end
-end

data/lib/swarm_sdk/concerns/validatable.rb

@@ -1,55 +0,0 @@
-# frozen_string_literal: true
-
-module SwarmSDK
-  module Concerns
-    # Shared validation functionality for Swarm and Workflow
-    #
-    # Both classes must have:
-    # - agent_definitions: Hash of Agent::Definition objects
-    # - swarm_id: Swarm/workflow identifier
-    # - parent_swarm_id: Parent identifier (or nil)
-    #
-    module Validatable
-      # Validate swarm/workflow configuration and return warnings
-      #
-      # This performs lightweight validation checks without creating agents.
-      # Useful for displaying configuration warnings before execution.
-      #
-      # @return [Array<Hash>] Array of warning hashes from all agent definitions
-      def validate
-        @agent_definitions.flat_map { |_name, definition| definition.validate }
-      end
-
-      # Emit validation warnings as log events
-      #
-      # This validates all agent definitions and emits any warnings as
-      # model_lookup_warning events through LogStream. Useful for emitting
-      # warnings before execution starts (e.g., in REPL after welcome screen).
-      #
-      # Requires LogStream.emitter to be set.
-      #
-      # @return [Array<Hash>] The validation warnings that were emitted
-      def emit_validation_warnings
-        warnings = validate
-
-        warnings.each do |warning|
-          case warning[:type]
-          when :model_not_found
-            LogStream.emit(
-              type: "model_lookup_warning",
-              agent: warning[:agent],
-              swarm_id: @swarm_id,
-              parent_swarm_id: @parent_swarm_id,
-              model: warning[:model],
-              error_message: warning[:error_message],
-              suggestions: warning[:suggestions],
-              timestamp: Time.now.utc.iso8601,
-            )
-          end
-        end
-
-        warnings
-      end
-    end
-  end
-end