swarm_sdk 2.0.0.pre.2

data/lib/swarm_sdk/agent/context.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module Agent
+    # AgentContext encapsulates per-agent state and metadata
+    #
+    # Each agent has its own context that tracks:
+    # - Agent identity (name)
+    # - Delegation relationships (which tool calls are delegations)
+    # - Context window warnings (which thresholds have been hit)
+    # - Optional metadata
+    #
+    # This class replaces the per-agent hash maps that were previously
+    # stored in UnifiedLogger.
+    #
+    # @example
+    #   context = Agent::Context.new(
+    #     name: :backend,
+    #     delegation_tools: ["DelegateToDatabase", "DelegateToAuth"],
+    #     metadata: { role: "backend" }
+    #   )
+    #
+    #   # Track a delegation
+    #   context.track_delegation(call_id: "call_123", target: "DelegateToDatabase")
+    #
+    #   # Check if a tool call is a delegation
+    #   context.delegation?(call_id: "call_123") # => true
+    class Context
+      # Thresholds for context limit warnings (in percentage)
+      CONTEXT_WARNING_THRESHOLDS = [80, 90].freeze
+
+      attr_reader :name, :delegation_tools, :metadata, :warning_thresholds_hit
+
+      # Initialize a new agent context
+      #
+      # @param name [Symbol, String] Agent name
+      # @param delegation_tools [Array<String>] Names of tools that are delegations
+      # @param metadata [Hash] Optional metadata about the agent
+      def initialize(name:, delegation_tools: [], metadata: {})
+        @name = name.to_sym
+        @delegation_tools = Set.new(delegation_tools.map(&:to_s))
+        @metadata = metadata
+        @delegation_call_ids = Set.new
+        @delegation_targets = {}
+        @warning_thresholds_hit = Set.new
+      end
+
+      # Track a delegation tool call
+      #
+      # @param call_id [String] Tool call ID
+      # @param target [String] Target agent/tool name
+      # @return [void]
+      def track_delegation(call_id:, target:)
+        @delegation_call_ids.add(call_id)
+        @delegation_targets[call_id] = target
+      end
+
+      # Check if a tool call is a delegation
+      #
+      # @param call_id [String] Tool call ID
+      # @return [Boolean]
+      def delegation?(call_id:)
+        @delegation_call_ids.include?(call_id)
+      end
+
+      # Get the delegation target for a tool call
+      #
+      # @param call_id [String] Tool call ID
+      # @return [String, nil] Target agent/tool name, or nil if not a delegation
+      def delegation_target(call_id:)
+        @delegation_targets[call_id]
+      end
+
+      # Remove a delegation from tracking (after it completes)
+      #
+      # @param call_id [String] Tool call ID
+      # @return [void]
+      def clear_delegation(call_id:)
+        @delegation_targets.delete(call_id)
+        @delegation_call_ids.delete(call_id)
+      end
+
+      # Check if a tool name is a delegation tool
+      #
+      # @param tool_name [String] Tool name
+      # @return [Boolean]
+      def delegation_tool?(tool_name)
+        @delegation_tools.include?(tool_name.to_s)
+      end
+
+      # Record that a context warning threshold has been hit
+      #
+      # @param threshold [Integer] Threshold percentage (80, 90, etc)
+      # @return [Boolean] true if this is the first time hitting this threshold
+      def hit_warning_threshold?(threshold)
+        !@warning_thresholds_hit.add?(threshold).nil?
+      end
+
+      # Check if a warning threshold has been hit
+      #
+      # @param threshold [Integer] Threshold percentage
+      # @return [Boolean]
+      def warning_threshold_hit?(threshold)
+        @warning_thresholds_hit.include?(threshold)
+      end
+    end
+  end
+end

data/lib/swarm_sdk/agent/definition.rb

@@ -0,0 +1,335 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module Agent
+    # Agent definition encapsulates agent configuration and builds system prompts
+    #
+    # This class is responsible for:
+    # - Parsing and validating agent configuration
+    # - Building the full system prompt (base + custom)
+    # - Handling tool permissions
+    # - Managing hooks (both DSL Ruby blocks and YAML shell commands)
+    #
+    # @example
+    #   definition = Agent::Definition.new(:backend, {
+    #     description: "Backend API developer",
+    #     model: "gpt-5",
+    #     tools: [:Read, :Write, :Bash],
+    #     system_prompt: "You build APIs"
+    #   })
+    class Definition
+      DEFAULT_MODEL = "gpt-5"
+      DEFAULT_PROVIDER = "openai"
+      DEFAULT_TIMEOUT = 300 # 5 minutes - reasoning models can take a while
+      BASE_SYSTEM_PROMPT_PATH = File.expand_path("../prompts/base_system_prompt.md.erb", __dir__)
+
+      attr_reader :name,
+        :description,
+        :model,
+        :context_window,
+        :directory,
+        :tools,
+        :delegates_to,
+        :system_prompt,
+        :provider,
+        :base_url,
+        :api_version,
+        :mcp_servers,
+        :parameters,
+        :headers,
+        :timeout,
+        :include_default_tools,
+        :skip_base_prompt,
+        :default_permissions,
+        :agent_permissions,
+        :assume_model_exists,
+        :hooks
+
+      attr_accessor :bypass_permissions, :max_concurrent_tools
+
+      def initialize(name, config = {})
+        @name = name.to_sym
+
+        # BREAKING CHANGE: Hard error for plural form
+        if config[:directories]
+          raise ConfigurationError,
+            "The 'directories' (plural) configuration is no longer supported in SwarmSDK 1.0+.\n\n" \
+              "Change 'directories:' to 'directory:' (singular).\n\n" \
+              "If you need access to multiple directories, use permissions:\n\n  " \
+              "directory: 'backend/'\n  " \
+              "permissions do\n    " \
+              "tool(:Read).allow_paths('../shared/**')\n  " \
+              "end"
+        end
+
+        @description = config[:description]
+        @model = config[:model] || DEFAULT_MODEL
+        @provider = config[:provider] || DEFAULT_PROVIDER
+        @base_url = config[:base_url]
+        @api_version = config[:api_version]
+        @context_window = config[:context_window] # Explicit context window override
+        @parameters = config[:parameters] || {}
+        @headers = Utils.stringify_keys(config[:headers] || {})
+        @timeout = config[:timeout] || DEFAULT_TIMEOUT
+        @bypass_permissions = config[:bypass_permissions] || false
+        @max_concurrent_tools = config[:max_concurrent_tools]
+        # Default to true when base_url is set, false otherwise (unless explicitly specified)
+        @assume_model_exists = if config.key?(:assume_model_exists)
+          config[:assume_model_exists]
+        else
+          (base_url ? true : false)
+        end
+
+        # include_default_tools defaults to true if not specified
+        @include_default_tools = config.key?(:include_default_tools) ? config[:include_default_tools] : true
+
+        # skip_base_prompt defaults to false if not specified
+        @skip_base_prompt = config.key?(:skip_base_prompt) ? config[:skip_base_prompt] : false
+
+        # Parse directory first so it can be used in system prompt rendering
+        @directory = parse_directory(config[:directory])
+
+        # Build system prompt after directory is set
+        @system_prompt = build_full_system_prompt(config[:system_prompt])
+
+        # Parse tools with permissions support
+        @default_permissions = config[:default_permissions] || {}
+        @agent_permissions = config[:permissions] || {}
+        @tools = parse_tools_with_permissions(
+          config[:tools],
+          @default_permissions,
+          @agent_permissions,
+        )
+
+        # Inject default write restrictions for security
+        @tools = inject_default_write_permissions(@tools)
+
+        @delegates_to = Array(config[:delegates_to] || []).map(&:to_sym)
+        @mcp_servers = Array(config[:mcp_servers] || [])
+
+        # Parse hooks configuration
+        # Handles both DSL (HookDefinition objects) and YAML (raw hash) formats
+        @hooks = parse_hooks(config[:hooks])
+
+        validate!
+      end
+
+      def to_h
+        {
+          name: @name,
+          description: @description,
+          model: @model,
+          directory: @directory,
+          tools: @tools,
+          delegates_to: @delegates_to,
+          system_prompt: @system_prompt,
+          provider: @provider,
+          base_url: @base_url,
+          api_version: @api_version,
+          mcp_servers: @mcp_servers,
+          parameters: @parameters,
+          headers: @headers,
+          timeout: @timeout,
+          bypass_permissions: @bypass_permissions,
+          include_default_tools: @include_default_tools,
+          skip_base_prompt: @skip_base_prompt,
+          assume_model_exists: @assume_model_exists,
+          max_concurrent_tools: @max_concurrent_tools,
+          hooks: @hooks,
+        }.compact
+      end
+
+      private
+
+      def build_full_system_prompt(custom_prompt)
+        # If skip_base_prompt is true, return only the custom prompt (or empty string if nil)
+        if @skip_base_prompt
+          return (custom_prompt || "").to_s
+        end
+
+        rendered_base = render_base_system_prompt
+
+        return rendered_base if custom_prompt.nil? || custom_prompt.strip.empty?
+
+        "#{rendered_base}\n\n#{custom_prompt}"
+      end
+
+      def render_base_system_prompt
+        cwd = @directory || Dir.pwd
+        platform = RUBY_PLATFORM
+        os_version = begin
+          %x(uname -sr 2>/dev/null).strip
+        rescue
+          RUBY_PLATFORM
+        end
+        date = Time.now.strftime("%Y-%m-%d")
+
+        template_content = File.read(BASE_SYSTEM_PROMPT_PATH)
+        ERB.new(template_content).result(binding)
+      end
+
+      def parse_directory(directory_config)
+        directory_config ||= "."
+        File.expand_path(directory_config.to_s)
+      end
+
+      # Parse tools configuration with permissions support
+      #
+      # Tools can be specified as:
+      # - Symbol: :Write (no permissions)
+      # - Hash: { Write: { allowed_paths: [...] } } (with permissions)
+      #
+      # Returns array of tool configs:
+      # [
+      #   { name: :Read, permissions: nil },
+      #   { name: :Write, permissions: { allowed_paths: [...] } }
+      # ]
+      def parse_tools_with_permissions(tools_config, default_permissions, agent_permissions)
+        tools_array = Array(tools_config || [])
+
+        tools_array.map do |tool_spec|
+          case tool_spec
+          when Symbol, String
+            # Simple tool: :Write or "Write"
+            tool_name = tool_spec.to_sym
+            permissions = resolve_permissions(tool_name, default_permissions, agent_permissions)
+
+            { name: tool_name, permissions: permissions }
+          when Hash
+            # Check if already in parsed format: { name: :Write, permissions: {...} }
+            if tool_spec.key?(:name)
+              # Already parsed - pass through as-is
+              tool_spec
+            else
+              # Tool with inline permissions: { Write: { allowed_paths: [...] } }
+              tool_name = tool_spec.keys.first.to_sym
+              inline_permissions = tool_spec.values.first
+
+              # Inline permissions override defaults
+              { name: tool_name, permissions: inline_permissions }
+            end
+          else
+            raise ConfigurationError, "Invalid tool specification: #{tool_spec.inspect}"
+          end
+        end
+      end
+
+      # Resolve permissions for a tool from defaults and agent-level overrides
+      def resolve_permissions(tool_name, default_permissions, agent_permissions)
+        # Agent-level permissions override defaults
+        agent_permissions[tool_name] || default_permissions[tool_name]
+      end
+
+      # Inject default write permissions for security
+      #
+      # Write, Edit, and MultiEdit tools without explicit permissions are automatically
+      # restricted to only write within the agent's directory. This prevents accidental
+      # writes outside the agent's working scope.
+      #
+      # Default permission: { allowed_paths: ["**/*"] }
+      # This is resolved relative to the agent's directory by the permissions system.
+      #
+      # Users can override by explicitly setting permissions for these tools.
+      def inject_default_write_permissions(tools)
+        write_tools = [:Write, :Edit, :MultiEdit]
+
+        tools.map do |tool_config|
+          tool_name = tool_config[:name]
+
+          # If it's a write tool and has no permissions, inject default
+          if write_tools.include?(tool_name) && tool_config[:permissions].nil?
+            tool_config.merge(permissions: { allowed_paths: ["**/*"] })
+          else
+            tool_config
+          end
+        end
+      end
+
+      # Parse hooks configuration
+      #
+      # Handles two input formats:
+      #
+      # 1. DSL format (from Agent::Builder): Pre-parsed HookDefinition objects
+      #    { event_type: [HookDefinition, ...] }
+      #    These are applied directly in pass_4_configure_hooks
+      #
+      # 2. YAML format: Raw hash with shell command specifications
+      #    hooks:
+      #      pre_tool_use:
+      #        - matcher: "Write|Edit"
+      #          type: command
+      #          command: "validate.sh"
+      #    These are kept raw and processed by Hooks::Adapter in pass_5
+      #
+      # Returns:
+      # - DSL: { event_type: [HookDefinition, ...] }
+      # - YAML: Raw hash (for Hooks::Adapter)
+      def parse_hooks(hooks_config)
+        return {} if hooks_config.nil? || hooks_config.empty?
+
+        # If already parsed from DSL (HookDefinition objects), return as-is
+        if hooks_config.is_a?(Hash) && hooks_config.values.all? { |v| v.is_a?(Array) && v.all? { |item| item.is_a?(Hooks::Definition) } }
+          return hooks_config
+        end
+
+        # For YAML hooks: validate structure but keep raw for Hooks::Adapter
+        validate_yaml_hooks(hooks_config)
+
+        # Return raw YAML - Hooks::Adapter will process in pass_5
+        hooks_config
+      end
+
+      # Validate YAML hooks structure
+      #
+      # @param hooks_config [Hash] YAML hooks configuration
+      # @return [void]
+      def validate_yaml_hooks(hooks_config)
+        hooks_config.each do |event_name, hook_specs|
+          event_sym = event_name.to_sym
+
+          # Validate event type
+          unless Hooks::Registry::VALID_EVENTS.include?(event_sym)
+            raise ConfigurationError,
+              "Invalid hook event '#{event_name}' for agent '#{@name}'. " \
+                "Valid events: #{Hooks::Registry::VALID_EVENTS.join(", ")}"
+          end
+
+          # Validate each hook spec structure
+          Array(hook_specs).each do |spec|
+            hook_type = spec[:type] || spec["type"]
+            command = spec[:command] || spec["command"]
+
+            raise ConfigurationError, "Hook missing 'type' field for event #{event_name}" unless hook_type
+            raise ConfigurationError, "Hook missing 'command' field for event #{event_name}" if hook_type.to_s == "command" && !command
+          end
+        end
+      end
+
+      def validate!
+        raise ConfigurationError, "Agent '#{@name}' missing required 'description' field" unless @description
+
+        # Validate api_version can only be set for OpenAI-compatible providers
+        if @api_version
+          openai_compatible = ["openai", "deepseek", "perplexity", "mistral", "openrouter"]
+          unless openai_compatible.include?(@provider.to_s)
+            raise ConfigurationError,
+              "Agent '#{@name}' has api_version set, but provider is '#{@provider}'. " \
+                "api_version can only be used with OpenAI-compatible providers: #{openai_compatible.join(", ")}"
+          end
+
+          # Validate api_version value
+          valid_versions = ["v1/chat/completions", "v1/responses"]
+          unless valid_versions.include?(@api_version)
+            raise ConfigurationError,
+              "Agent '#{@name}' has invalid api_version '#{@api_version}'. " \
+                "Valid values: #{valid_versions.join(", ")}"
+          end
+        end
+
+        unless File.directory?(@directory)
+          raise ConfigurationError, "Directory '#{@directory}' for agent '#{@name}' does not exist"
+        end
+      end
+    end
+  end
+end

data/lib/swarm_sdk/configuration.rb

@@ -0,0 +1,251 @@
+# 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
+
+    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,
+      )
+
+      # 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] || {}
+    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
+    end
+
+    def load_agents
+      swarm_agents = @config[:swarm][:agents]
+
+      swarm_agents.each do |name, agent_config|
+        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]
+          load_agent_from_file(name, agent_config[:agent_file], merged_config)
+        else
+          Agent::Definition.new(name, merged_config)
+        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
+    def merge_all_agents_config(agent_config)
+      merged = @all_agents_config.dup
+
+      # For arrays (like tools, delegates_to), concatenate instead of replace
+      # 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)
+        else
+          # For everything else, 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: markdown file overrides merged_config for fields it defines
+      final_config = merged_config.merge(agent_def_from_file.to_h.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