swarm_memory 2.1.5 → 2.1.6

data/lib/swarm_sdk/swarm/all_agents_builder.rb

@@ -1,167 +0,0 @@
-# frozen_string_literal: true
-
-module SwarmSDK
-  class Swarm
-    # AllAgentsBuilder for configuring settings that apply to all agents
-    #
-    # Settings configured here are applied to ALL agents, but can be overridden
-    # at the agent level. This is useful for shared configuration like:
-    # - Common provider/base_url (all agents use same proxy)
-    # - Shared timeout settings
-    # - Global permissions
-    #
-    # @example
-    #   all_agents do
-    #     provider :openai
-    #     base_url "http://proxy.com/v1"
-    #     timeout 180
-    #     tools :Read, :Write
-    #     coding_agent false
-    #   end
-    class AllAgentsBuilder
-      attr_reader :hooks, :permissions_config, :tools_list
-
-      def initialize
-        @tools_list = []
-        @hooks = []
-        @permissions_config = {}
-        @model = nil
-        @provider = nil
-        @base_url = nil
-        @api_version = nil
-        @timeout = nil
-        @parameters = nil
-        @headers = nil
-        @coding_agent = nil
-        @disable_default_tools = nil
-      end
-
-      # Set model for all agents
-      def model(model_name)
-        @model = model_name
-      end
-
-      # Set provider for all agents
-      def provider(provider_name)
-        @provider = provider_name
-      end
-
-      # Set base URL for all agents
-      def base_url(url)
-        @base_url = url
-      end
-
-      # Set API version for all agents
-      def api_version(version)
-        @api_version = version
-      end
-
-      # Set timeout for all agents
-      def timeout(seconds)
-        @timeout = seconds
-      end
-
-      # Set parameters for all agents
-      def parameters(params)
-        @parameters = params
-      end
-
-      # Set headers for all agents
-      def headers(header_hash)
-        @headers = header_hash
-      end
-
-      # Set coding_agent flag for all agents
-      def coding_agent(enabled)
-        @coding_agent = enabled
-      end
-
-      # Disable default tools for all agents
-      #
-      # @param value [Boolean, Array<Symbol>]
-      #   - true: Disable ALL default tools
-      #   - Array of symbols: Disable specific tools (e.g., [:Think, :TodoWrite])
-      def disable_default_tools(value)
-        @disable_default_tools = value
-      end
-
-      # Add tools that all agents will have
-      def tools(*tool_names)
-        @tools_list.concat(tool_names)
-      end
-
-      # Add hook for all agents (agent-level events only)
-      #
-      # @example
-      #   hook :pre_tool_use, matcher: "Write" do |ctx|
-      #     # Applies to all agents
-      #   end
-      def hook(event, matcher: nil, command: nil, timeout: nil, &block)
-        # Validate agent-level events
-        agent_events = [
-          :pre_tool_use,
-          :post_tool_use,
-          :user_prompt,
-          :agent_step,
-          :agent_stop,
-          :first_message,
-          :pre_delegation,
-          :post_delegation,
-          :context_warning,
-        ]
-
-        unless agent_events.include?(event)
-          raise ArgumentError, "Invalid all_agents hook: #{event}. Swarm-level events (:swarm_start, :swarm_stop) cannot be used in all_agents block."
-        end
-
-        @hooks << { event: event, matcher: matcher, command: command, timeout: timeout, block: block }
-      end
-
-      # Configure permissions for all agents
-      #
-      # Supports two forms:
-      # 1. Block form (DSL): permissions do ... end
-      # 2. Direct hash (internal/YAML): set_permissions_hash(hash)
-      #
-      # @example Block form
-      #   permissions do
-      #     Write.allow_paths "tmp/**/*"
-      #     Write.deny_paths "tmp/secrets/**"
-      #     Bash.allow_commands "^git status$"
-      #   end
-      def permissions(&block)
-        @permissions_config = PermissionsBuilder.build(&block)
-      end
-
-      # Set permissions directly from hash (for YAML translation)
-      #
-      # This is intentionally separate from permissions() to keep the DSL clean.
-      # Called by Configuration when translating YAML permissions.
-      #
-      # @param hash [Hash] Permissions configuration hash
-      # @return [void]
-      def permissions_hash=(hash)
-        @permissions_config = hash || {}
-      end
-
-      # Convert to hash for merging with agent configs
-      #
-      # @return [Hash] Configuration hash
-      def to_h
-        {
-          model: @model,
-          provider: @provider,
-          base_url: @base_url,
-          api_version: @api_version,
-          timeout: @timeout,
-          parameters: @parameters,
-          headers: @headers,
-          coding_agent: @coding_agent,
-          disable_default_tools: @disable_default_tools,
-          tools: @tools_list,
-          permissions: @permissions_config,
-        }.compact
-      end
-    end
-  end
-end

data/lib/swarm_sdk/swarm/builder.rb

@@ -1,249 +0,0 @@
-# frozen_string_literal: true
-
-module SwarmSDK
-  class Swarm
-    # Builder provides a beautiful Ruby DSL for building swarms
-    #
-    # The DSL combines YAML simplicity with Ruby power, enabling:
-    # - Fluent, chainable configuration
-    # - Hooks as Ruby blocks OR shell commands
-    # - Full Ruby language features (variables, conditionals, loops)
-    # - Type-safe, IDE-friendly API
-    #
-    # @example Basic usage
-    #   swarm = SwarmSDK.build do
-    #     name "Dev Team"
-    #     lead :backend
-    #
-    #     agent :backend do
-    #       model "gpt-5"
-    #       prompt "You build APIs"
-    #       tools :Read, :Write, :Bash
-    #
-    #       # Hook as Ruby block - inline logic!
-    #       hook :pre_tool_use, matcher: "Bash" do |ctx|
-    #         SwarmSDK::Hooks::Result.halt("Blocked!") if ctx.tool_call.parameters[:command].include?("rm -rf")
-    #       end
-    #     end
-    #   end
-    #
-    #   swarm.execute("Build auth API")
-    class Builder < Builders::BaseBuilder
-      # Main entry point for DSL
-      #
-      # @example
-      #   swarm = SwarmSDK.build do
-      #     name "Team"
-      #     agent :backend { ... }
-      #   end
-      class << self
-        def build(allow_filesystem_tools: nil, &block)
-          builder = new(allow_filesystem_tools: allow_filesystem_tools)
-          builder.instance_eval(&block)
-          builder.build_swarm
-        end
-      end
-
-      def initialize(allow_filesystem_tools: nil)
-        super
-        @lead_agent = nil
-        @swarm_hooks = []
-        @observer_configs = []
-      end
-
-      # Set lead agent
-      def lead(agent_name)
-        @lead_agent = agent_name
-      end
-
-      # Define observer agent behavior
-      #
-      # Configures an agent to run in parallel with main execution,
-      # triggered by specific events. The block defines event handlers.
-      #
-      # @param agent_name [Symbol] Name of agent to use as observer (must be defined)
-      # @param options [Hash] Optional observer settings (timeout, max_concurrent, etc.)
-      # @yield Observer configuration block
-      #
-      # @example Basic observer
-      #   observer :profiler do
-      #     on :swarm_start do |event|
-      #       "Analyze this prompt: #{event[:prompt]}"
-      #     end
-      #   end
-      #
-      # @example Observer with options
-      #   observer :monitor, timeout: 120 do
-      #     on :tool_call do |event|
-      #       next unless event[:tool_name] == "Bash"
-      #       "Check command: #{event[:arguments][:command]}"
-      #     end
-      #   end
-      def observer(agent_name, **options, &block)
-        unless @agents.key?(agent_name)
-          raise ConfigurationError,
-            "Observer agent '#{agent_name}' not defined. " \
-              "Define the agent first with `agent :#{agent_name} do ... end`"
-        end
-
-        config = Observer::Config.new(agent_name)
-        config.options.merge!(options) if options.any?
-        builder = Observer::Builder.new(agent_name, config)
-        builder.instance_eval(&block)
-
-        @observer_configs << config
-      end
-
-      # Add swarm-level hook (swarm_start, swarm_stop only)
-      #
-      # @example Shell command
-      #   hook :swarm_start, command: "echo 'Starting' >> log.txt"
-      #
-      # @example Ruby block
-      #   hook :swarm_start do |ctx|
-      #     puts "Swarm starting: #{ctx.metadata[:prompt]}"
-      #   end
-      def hook(event, command: nil, timeout: nil, &block)
-        # Validate swarm-level events
-        unless [:swarm_start, :swarm_stop].include?(event)
-          raise ArgumentError, "Invalid swarm-level hook: #{event}. Only :swarm_start and :swarm_stop allowed at swarm level. Use all_agents { hook ... } or agent { hook ... } for other events."
-        end
-
-        @swarm_hooks << { event: event, command: command, timeout: timeout, block: block }
-      end
-
-      # Build the actual Swarm instance
-      def build_swarm
-        raise ConfigurationError, "Swarm name not set. Use: name 'My Swarm'" unless @swarm_name
-        raise ConfigurationError, "No agents defined. Use: agent :name { ... }" if @agents.empty?
-        raise ConfigurationError, "Lead agent not set. Use: lead :agent_name" unless @lead_agent
-
-        # Validate filesystem tools BEFORE building
-        validate_all_agents_filesystem_tools if @all_agents_config
-        validate_agent_filesystem_tools
-
-        build_single_swarm
-      end
-
-      private
-
-      # Build a traditional single-swarm execution
-      #
-      # @return [Swarm] Configured swarm instance
-      def build_single_swarm
-        # Validate swarm_id is set if external swarms are registered (required for composable swarms)
-        if @swarm_registry_config.any? && @swarm_id.nil?
-          raise ConfigurationError, "Swarm id must be set using id(...) when using composable swarms"
-        end
-
-        # Create swarm using SDK (swarm_id auto-generates if nil)
-        swarm = Swarm.new(
-          name: @swarm_name,
-          swarm_id: @swarm_id,
-          scratchpad_mode: @scratchpad,
-          allow_filesystem_tools: @allow_filesystem_tools,
-        )
-
-        # Setup swarm registry if external swarms are registered
-        if @swarm_registry_config.any?
-          registry = SwarmRegistry.new(parent_swarm_id: @swarm_id)
-          @swarm_registry_config.each do |reg|
-            registry.register(reg[:name], source: reg[:source], keep_context: reg[:keep_context])
-          end
-          swarm.swarm_registry = registry
-        end
-
-        # Build agent definitions and add to swarm
-        agent_definitions = build_agent_definitions
-        agent_definitions.each_value do |definition|
-          swarm.add_agent(definition)
-        end
-
-        # Set lead
-        swarm.lead = @lead_agent
-
-        # Apply swarm hooks (Ruby blocks)
-        @swarm_hooks.each do |hook_config|
-          apply_swarm_hook(swarm, hook_config)
-        end
-
-        # Apply all_agents hooks (Ruby blocks)
-        @all_agents_config&.hooks&.each do |hook_config|
-          apply_all_agents_hook(swarm, hook_config)
-        end
-
-        # Add observer configurations to swarm
-        @observer_configs.each { |c| swarm.add_observer_config(c) }
-
-        swarm
-      end
-
-      def apply_swarm_hook(swarm, config)
-        event = config[:event]
-
-        if config[:block]
-          # Ruby block hook - register directly
-          swarm.add_default_callback(event, &config[:block])
-        elsif config[:command]
-          # Shell command hook - use ShellExecutor
-          swarm.add_default_callback(event) do |context|
-            input_json = build_hook_input(context, event)
-            Hooks::ShellExecutor.execute(
-              command: config[:command],
-              input_json: input_json,
-              timeout: config[:timeout] || 60,
-              swarm_name: swarm.name,
-              event: event,
-            )
-          end
-        end
-      end
-
-      def apply_all_agents_hook(swarm, config)
-        event = config[:event]
-        matcher = config[:matcher]
-
-        if config[:block]
-          # Ruby block hook
-          swarm.add_default_callback(event, matcher: matcher, &config[:block])
-        elsif config[:command]
-          # Shell command hook
-          swarm.add_default_callback(event, matcher: matcher) do |context|
-            input_json = build_hook_input(context, event)
-            Hooks::ShellExecutor.execute(
-              command: config[:command],
-              input_json: input_json,
-              timeout: config[:timeout] || 60,
-              agent_name: context.agent_name,
-              swarm_name: swarm.name,
-              event: event,
-            )
-          end
-        end
-      end
-
-      def build_hook_input(context, event)
-        # Build JSON input for shell hooks
-        base = { event: event.to_s }
-
-        case event
-        when :pre_tool_use
-          base.merge(tool: context.tool_call.name, parameters: context.tool_call.parameters)
-        when :post_tool_use
-          base.merge(result: context.tool_result.content, success: context.tool_result.success?)
-        when :user_prompt
-          base.merge(prompt: context.metadata[:prompt])
-        when :swarm_start
-          base.merge(prompt: context.metadata[:prompt])
-        when :swarm_stop
-          base.merge(success: context.metadata[:success], duration: context.metadata[:duration])
-        else
-          base
-        end
-      end
-    end
-
-    # Helper class for swarms block in DSL (kept in this file for reference)
-    # Actual implementation is in swarm_registry_builder.rb for Zeitwerk
-  end
-end

data/lib/swarm_sdk/swarm/executor.rb

@@ -1,213 +0,0 @@
-# frozen_string_literal: true
-
-module SwarmSDK
-  class Swarm
-    # Handles swarm execution orchestration
-    #
-    # Extracted from Swarm#execute to reduce complexity and eliminate code duplication.
-    # The core execution loop, error handling, and cleanup logic are unified here.
-    class Executor
-      def initialize(swarm)
-        @swarm = swarm
-      end
-
-      # Execute the swarm with a prompt
-      #
-      # @param prompt [String] User prompt
-      # @param wait [Boolean] Block until completion (true) or return task (false)
-      # @param logs [Array] Log collection array
-      # @param has_logging [Boolean] Whether logging is enabled
-      # @param original_fiber_storage [Hash] Original Fiber storage values to restore
-      # @return [Async::Task] The execution task
-      def run(prompt, wait:, logs:, has_logging:, original_fiber_storage:)
-        @original_fiber_storage = original_fiber_storage
-        if wait
-          run_blocking(prompt, logs: logs, has_logging: has_logging)
-        else
-          run_async(prompt, logs: logs, has_logging: has_logging)
-        end
-      end
-
-      private
-
-      # Blocking execution using Sync
-      def run_blocking(prompt, logs:, has_logging:)
-        Sync do |task|
-          execute_in_task(prompt, logs: logs, has_logging: has_logging) do |lead, current_prompt|
-            task.async(finished: false) { lead.ask(current_prompt) }.wait
-          end
-        ensure
-          # Always wait for observer tasks, even if main execution raises
-          # This is INSIDE Sync block, so async tasks can still complete
-          @swarm.wait_for_observers
-        end
-      ensure
-        # Restore original fiber storage (preserves parent context for nested swarms)
-        restore_fiber_storage
-      end
-
-      # Non-blocking execution using parent async task
-      def run_async(prompt, logs:, has_logging:)
-        parent = Async::Task.current
-        raise ConfigurationError, "wait: false requires an async context. Use Sync { swarm.execute(..., wait: false) }" unless parent
-
-        parent.async(finished: false) do
-          execute_in_task(prompt, logs: logs, has_logging: has_logging) do |lead, current_prompt|
-            Async(finished: false) { lead.ask(current_prompt) }.wait
-          end
-        end
-      end
-
-      # Core execution logic (unified, no duplication)
-      #
-      # @param prompt [String] Initial prompt
-      # @param logs [Array] Log collection
-      # @param has_logging [Boolean] Whether logging is enabled
-      # @yield [lead, current_prompt] Block to execute LLM call
-      # @return [Result] Execution result
-      def execute_in_task(prompt, logs:, has_logging:, &block)
-        start_time = Time.now
-        result = nil
-        swarm_stop_triggered = false
-        current_prompt = prompt
-
-        begin
-          # Notify plugins that swarm is starting
-          PluginRegistry.emit_event(:on_swarm_started, swarm: @swarm)
-
-          result = execution_loop(current_prompt, logs, start_time, &block)
-          swarm_stop_triggered = true
-        rescue ConfigurationError, AgentNotFoundError
-          # Re-raise configuration errors - these should be fixed, not caught
-          raise
-        rescue TypeError => e
-          result = handle_type_error(e, logs, start_time)
-        rescue StandardError => e
-          result = handle_standard_error(e, logs, start_time)
-        ensure
-          # Notify plugins that swarm is stopping (called even on error)
-          PluginRegistry.emit_event(:on_swarm_stopped, swarm: @swarm)
-
-          cleanup_after_execution(result, start_time, logs, swarm_stop_triggered, has_logging)
-        end
-
-        result
-      end
-
-      # Main execution loop with reprompting support
-      def execution_loop(initial_prompt, logs, start_time)
-        current_prompt = initial_prompt
-
-        loop do
-          lead = @swarm.agents[@swarm.lead_agent]
-          response = yield(lead, current_prompt)
-
-          # Check if swarm was finished by a hook (finish_swarm)
-          if response.is_a?(Hash) && response[:__finish_swarm__]
-            result = build_result(response[:message], logs, start_time)
-            @swarm.trigger_swarm_stop(result)
-            return result
-          end
-
-          result = build_result(response.content, logs, start_time)
-
-          # Trigger swarm_stop hooks (for reprompt check and event emission)
-          hook_result = @swarm.trigger_swarm_stop(result)
-
-          # Check if hook requests reprompting
-          if hook_result&.reprompt?
-            current_prompt = hook_result.value
-            # Continue loop with new prompt
-          else
-            # Exit loop - execution complete
-            return result
-          end
-        end
-      end
-
-      # Build a Result object
-      def build_result(content, logs, start_time)
-        Result.new(
-          content: content,
-          agent: @swarm.lead_agent.to_s,
-          logs: logs,
-          duration: Time.now - start_time,
-        )
-      end
-
-      # Handle TypeError (e.g., "String does not have #dig method")
-      def handle_type_error(error, logs, start_time)
-        if error.message.include?("does not have #dig method")
-          agent_definition = @swarm.agent_definitions[@swarm.lead_agent]
-          error_msg = if agent_definition.base_url
-            "LLM API request failed: The proxy/server at '#{agent_definition.base_url}' returned an invalid response. " \
-              "This usually means the proxy is unreachable, requires authentication, or returned an error in non-JSON format. " \
-              "Original error: #{error.message}"
-          else
-            "LLM API request failed with unexpected response format. Original error: #{error.message}"
-          end
-
-          Result.new(
-            content: nil,
-            agent: @swarm.lead_agent.to_s,
-            error: LLMError.new(error_msg),
-            logs: logs,
-            duration: Time.now - start_time,
-          )
-        else
-          Result.new(
-            content: nil,
-            agent: @swarm.lead_agent.to_s,
-            error: error,
-            logs: logs,
-            duration: Time.now - start_time,
-          )
-        end
-      end
-
-      # Handle StandardError
-      def handle_standard_error(error, logs, start_time)
-        Result.new(
-          content: nil,
-          agent: @swarm.lead_agent&.to_s || "unknown",
-          error: error,
-          logs: logs,
-          duration: Time.now - start_time,
-        )
-      end
-
-      # Cleanup after execution (ensure block logic)
-      def cleanup_after_execution(result, start_time, logs, swarm_stop_triggered, has_logging)
-        # Trigger swarm_stop if not already triggered (handles error cases)
-        unless swarm_stop_triggered
-          @swarm.trigger_swarm_stop_final(result, start_time, logs)
-        end
-
-        # Cleanup MCP clients after execution
-        @swarm.cleanup
-
-        # Cleanup observer subscriptions (matches MCP cleanup pattern)
-        @swarm.cleanup_observers
-
-        # Restore original Fiber storage (preserves parent context for nested swarms)
-        restore_fiber_storage
-
-        # Reset logging state for next execution if we set it up
-        reset_logging if has_logging
-      end
-
-      # Restore Fiber-local storage to original values (preserves parent context)
-      def restore_fiber_storage
-        Fiber[:execution_id] = @original_fiber_storage[:execution_id]
-        Fiber[:swarm_id] = @original_fiber_storage[:swarm_id]
-        Fiber[:parent_swarm_id] = @original_fiber_storage[:parent_swarm_id]
-      end
-
-      # Reset logging state
-      def reset_logging
-        LogCollector.reset!
-        LogStream.reset!
-      end
-    end
-  end
-end