swarm_sdk 2.7.12 → 2.7.14

data/lib/swarm_sdk/ruby_llm_patches/mcp_ssl_patch.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+# Patches ruby_llm-mcp HTTPX connections to configure SSL verification
+#
+# OpenSSL 3.6 enforces CRL (Certificate Revocation List) checking by default.
+# Most certificates don't provide accessible CRL endpoints (industry moved to OCSP),
+# which breaks HTTPS MCP connections with:
+#   "certificate verify failed (unable to get certificate CRL)"
+#
+# This patch injects SSL options into all 5 HTTPX connection creation paths:
+#
+# Via HTTPClient.build_connection (paths 1-3):
+#   1. StreamableHTTP#create_connection
+#   2. StreamableHTTP#create_connection_with_streaming_callbacks
+#   3. SSE#send_request
+#
+# Direct HTTPX.plugin calls (paths 4-5):
+#   4. StreamableHTTP#create_connection_with_sse_callbacks
+#   5. SSE#create_sse_client
+#
+# Default: VERIFY_PEER (validates cert chain without CRL checking)
+# Configurable: VERIFY_NONE for local development via SwarmSDK.config.mcp_ssl_verify
+
+require "openssl"
+
+module SwarmSDK
+  # Module-level SSL configuration for MCP HTTPX connections
+  #
+  # Set ssl_options before creating MCP clients. The patched HTTPX methods
+  # read from this accessor to configure SSL on every connection.
+  #
+  # @example Default (validates cert chain, skips CRL)
+  #   McpSslPatch.ssl_options #=> { verify_mode: OpenSSL::SSL::VERIFY_PEER }
+  #
+  # @example Disable SSL verification (local dev only)
+  #   McpSslPatch.ssl_options = { verify_mode: OpenSSL::SSL::VERIFY_NONE }
+  module McpSslPatch
+    @ssl_options = { verify_mode: OpenSSL::SSL::VERIFY_PEER }
+
+    class << self
+      # @return [Hash] SSL options hash passed to HTTPX .with(ssl: ...)
+      attr_accessor :ssl_options
+
+      # Clear the thread-local HTTPX connection cache
+      #
+      # Must be called after changing ssl_options so that HTTPClient.build_connection
+      # runs again with the updated options.
+      #
+      # @return [void]
+      def reset_connection!
+        Thread.current[:ruby_llm_mcp_client_connection] = nil
+      end
+    end
+  end
+end
+
+# Patch 1: HTTPClient.build_connection
+#
+# Covers paths 1-3: StreamableHTTP#create_connection,
+# StreamableHTTP#create_connection_with_streaming_callbacks, SSE#send_request
+#
+# These all chain from HTTPClient.connection which calls build_connection.
+module RubyLLM
+  module MCP
+    module Transports
+      module Support
+        class HTTPClient
+          class << self
+            def build_connection
+              HTTPX.with(
+                pool_options: {
+                  max_connections: RubyLLM::MCP.config.max_connections,
+                  pool_timeout: RubyLLM::MCP.config.pool_timeout,
+                },
+                ssl: SwarmSDK::McpSslPatch.ssl_options,
+              )
+            end
+          end
+        end
+      end
+    end
+  end
+end
+
+# Patch 2: StreamableHTTP#create_connection_with_sse_callbacks
+#
+# This method calls HTTPX.plugin(:callbacks) directly, bypassing HTTPClient.
+# Merges SSL options with ALPN protocol when version is :http1.
+module SwarmSDK
+  module McpSslPatch
+    module StreamableHttpSslPatch
+      private
+
+      def create_connection_with_sse_callbacks(options, headers)
+        client = HTTPX.plugin(:callbacks)
+        client = add_on_response_body_chunk_callback(client, options)
+
+        ssl = SwarmSDK::McpSslPatch.ssl_options.dup
+        ssl[:alpn_protocols] = ["http/1.1"] if @version == :http1
+
+        client = client.with(
+          timeout: {
+            connect_timeout: 10,
+            read_timeout: @request_timeout / 1000,
+            write_timeout: @request_timeout / 1000,
+            operation_timeout: @request_timeout / 1000,
+          },
+          headers: headers,
+          ssl: ssl,
+        )
+
+        register_client(client)
+      end
+    end
+  end
+end
+
+# Patch 3: SSE#create_sse_client
+#
+# This method calls HTTPX.plugin(:stream) directly, bypassing HTTPClient.
+# Merges SSL options with ALPN protocol when version is :http1.
+module SwarmSDK
+  module McpSslPatch
+    module SseSslPatch
+      private
+
+      def create_sse_client
+        stream_headers = build_request_headers
+
+        ssl = SwarmSDK::McpSslPatch.ssl_options.dup
+        ssl[:alpn_protocols] = ["http/1.1"] if @version == :http1
+
+        HTTPX.plugin(:stream).with(
+          headers: stream_headers,
+          ssl: ssl,
+        )
+      end
+    end
+  end
+end
+
+# Apply prepend patches for direct HTTPX.plugin calls
+RubyLLM::MCP::Transports::StreamableHTTP.prepend(SwarmSDK::McpSslPatch::StreamableHttpSslPatch)
+RubyLLM::MCP::Transports::SSE.prepend(SwarmSDK::McpSslPatch::SseSslPatch)

data/lib/swarm_sdk/ruby_llm_patches/tool_concurrency_patch.rb

@@ -88,11 +88,15 @@ module RubyLLM
               "Add `gem 'async'` to your Gemfile. Original error: #{e.message}"
         end
 
-        def run_with_sync(&)
-          if defined?(Sync)
-            Sync(&)
+        def run_with_sync(&block)
+          if Async::Task.current?
+            # Already inside an async reactor (SwarmSDK always runs in one).
+            # Just yield — no Sync, no nested reactor, no Promise mutex issues.
+            yield
           else
-            Async(&).wait
+            # Outside async context (e.g., standalone RubyLLM usage).
+            # Sync handles reactor creation and cleanup.
+            Sync(&block)
           end
         end
 
@@ -145,14 +149,13 @@ module RubyLLM
 
       private
 
-      # Override handle_tool_calls to support concurrent execution
-      # This method is called when tool_concurrency is set
+      # Override handle_tool_calls to support concurrent execution.
+      # Returns halt result or nil — the trampoline loop in complete() handles the next iteration.
       def handle_tool_calls(response, &block)
         return super unless @tool_concurrency
 
         tool_calls = response.tool_calls
-        halt_result = execute_tools_concurrently(tool_calls)
-        halt_result || complete(&block)
+        execute_tools_concurrently(tool_calls)
       end
 
       def execute_tools_concurrently(tool_calls)

data/lib/swarm_sdk/swarm/all_agents_builder.rb

@@ -37,6 +37,7 @@ module SwarmSDK
         @disable_default_tools = nil
         @streaming = nil
         @thinking = nil
+        @disable_environment_info = nil
       end
 
       # Set model for all agents
@@ -100,6 +101,13 @@ module SwarmSDK
         @streaming = value
       end
 
+      # Disable environment info for all agents
+      #
+      # @param enabled [Boolean] Whether to disable environment info in system prompts
+      def disable_environment_info(enabled)
+        @disable_environment_info = enabled
+      end
+
       # Configure extended thinking for all agents
       #
       # @param effort [Symbol, String, nil] Reasoning effort (:low, :medium, :high) — OpenAI
@@ -186,6 +194,7 @@ module SwarmSDK
           disable_default_tools: @disable_default_tools,
           streaming: @streaming,
           thinking: @thinking,
+          disable_environment_info: @disable_environment_info,
           tools: @tools_list,
           permissions: @permissions_config,
         }.compact

data/lib/swarm_sdk/swarm/executor.rb

@@ -6,9 +6,19 @@ module SwarmSDK
     #
     # Extracted from Swarm#execute to reduce complexity and eliminate code duplication.
     # The core execution loop, error handling, and cleanup logic are unified here.
+    #
+    # ## Stop Mechanism
+    #
+    # Supports hard-stop via `swarm.stop` using IO.pipe for thread-safe signaling:
+    # 1. `swarm.stop` writes to pipe and sets `@stop_requested`
+    # 2. A listener task reads from the pipe (async-aware I/O)
+    # 3. Listener calls `barrier.stop` within the Async reactor
+    # 4. All child tasks receive `Async::Stop` exception
+    # 5. `execute_in_task` catches `Async::Stop`, sets interrupted flag, emits events
     class Executor
       def initialize(swarm)
         @swarm = swarm
+        @interrupted_result = nil
       end
 
       # Execute the swarm with a prompt
@@ -18,7 +28,7 @@ module SwarmSDK
       # @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
+      # @return [Result, Async::Task] Result if wait: true, Async::Task if wait: false
       def run(prompt, wait:, logs:, has_logging:, original_fiber_storage:)
         @original_fiber_storage = original_fiber_storage
         if wait
@@ -31,19 +41,39 @@ module SwarmSDK
       private
 
       # Blocking execution using Sync
+      #
+      # Wraps execution in an Async::Barrier so `swarm.stop` can cancel all tasks.
+      # A stop listener task watches the IO.pipe for stop signals.
       def run_blocking(prompt, logs:, has_logging:)
         result = nil
+        start_time = Time.now
+        @swarm.prepare_for_execution
+
         Sync do |task|
-          start_time = Time.now
+          barrier = Async::Barrier.new
+          @swarm.register_execution_barrier(barrier)
+          stop_listener = setup_stop_listener(task, barrier)
+
+          begin
+            result = barrier.async do
+              if @swarm.execution_timeout
+                execute_with_execution_timeout(task, prompt, logs, has_logging, start_time)
+              else
+                execute_in_task(prompt, logs: logs, has_logging: has_logging) do |lead, current_prompt|
+                  lead.ask(current_prompt)
+                end
+              end
+            end.wait
 
-          result = if @swarm.execution_timeout
-            execute_with_execution_timeout(task, prompt, logs, has_logging, start_time)
-          else
-            execute_in_task(prompt, logs: logs, has_logging: has_logging) do |lead, current_prompt|
-              # Execute directly - no child task needed
-              # This keeps execution in same fiber context for better control
-              lead.ask(current_prompt)
-            end
+            # barrier child .wait returns nil when stopped
+            result = @interrupted_result if result.nil? && @swarm.stop_requested?
+          rescue Async::Stop
+            # Non-blocking path (rare - user called task.stop on Sync root)
+            result = @interrupted_result
+          ensure
+            barrier.stop unless barrier.empty?
+            stop_listener&.stop
+            @swarm.clear_execution_barrier
           end
         ensure
           # Always wait for observer tasks, even if main execution raises
@@ -53,32 +83,77 @@ module SwarmSDK
 
         result
       ensure
-        # Restore original fiber storage (preserves parent context for nested swarms)
+        @interrupted_result = nil
+        @swarm.cleanup_stop_signal
         restore_fiber_storage
       end
 
       # Non-blocking execution using parent async task
+      #
+      # Same barrier + stop listener pattern as run_blocking.
       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
 
+        @swarm.prepare_for_execution
+
         # NOTE: The block receives |task| as the spawned Async::Task when arity > 0
         parent.async(finished: false) do |task|
           start_time = Time.now
+          barrier = Async::Barrier.new
+          @swarm.register_execution_barrier(barrier)
+          stop_listener = setup_stop_listener(task, barrier)
+
+          begin
+            result = barrier.async do
+              if @swarm.execution_timeout
+                execute_with_execution_timeout(task, prompt, logs, has_logging, start_time)
+              else
+                execute_in_task(prompt, logs: logs, has_logging: has_logging) do |lead, current_prompt|
+                  lead.ask(current_prompt)
+                end
+              end
+            end.wait
 
-          if @swarm.execution_timeout
-            execute_with_execution_timeout(task, prompt, logs, has_logging, start_time)
-          else
-            execute_in_task(prompt, logs: logs, has_logging: has_logging) do |lead, current_prompt|
-              # Execute directly - no child task needed
-              lead.ask(current_prompt)
-            end
+            result = @interrupted_result if result.nil? && @swarm.stop_requested?
+            result
+          rescue Async::Stop
+            @interrupted_result
+          ensure
+            barrier.stop unless barrier.empty?
+            stop_listener&.stop
+            @swarm.clear_execution_barrier
+            @interrupted_result = nil
+            @swarm.cleanup_stop_signal
+            @swarm.wait_for_observers
           end
         end
       end
 
+      # Setup a listener task that watches for stop signals via IO.pipe
+      #
+      # The listener reads from the pipe (async-aware I/O that yields to scheduler).
+      # When data arrives (from `swarm.stop`), it stops the barrier to cancel all tasks.
+      #
+      # @param task [Async::Task] Parent task to spawn listener under
+      # @param barrier [Async::Barrier] Execution barrier to stop
+      # @return [Async::Task, nil] The listener task, or nil if no pipe
+      def setup_stop_listener(task, barrier)
+        return unless @swarm.stop_signal_read
+
+        task.async do
+          @swarm.stop_signal_read.read(1) # Async-aware I/O, yields to scheduler
+          barrier.stop unless barrier.empty?
+        rescue IOError, Async::Stop
+          # Pipe closed or listener stopped - normal cleanup
+        end
+      end
+
       # Core execution logic (unified, no duplication)
       #
+      # Handles InterruptedError and Async::Stop to properly track interruption state.
+      # The interrupted flag drives cleanup behavior (event emission, result building).
+      #
       # @param prompt [String] Initial prompt
       # @param logs [Array] Log collection
       # @param has_logging [Boolean] Whether logging is enabled
@@ -89,6 +164,7 @@ module SwarmSDK
         result = nil
         swarm_stop_triggered = false
         current_prompt = prompt
+        interrupted = false
 
         begin
           # Notify plugins that swarm is starting
@@ -100,6 +176,12 @@ module SwarmSDK
           # Re-raise configuration errors and timeouts - these should not be caught here
           # Timeouts are handled by execute_with_execution_timeout wrapper
           raise
+        rescue InterruptedError
+          interrupted = true
+          raise
+        rescue Async::Stop
+          interrupted = true
+          raise # Must re-raise for Async task cleanup
         rescue TypeError => e
           result = handle_type_error(e, logs, start_time)
         rescue StandardError => e
@@ -108,17 +190,30 @@ module SwarmSDK
           # 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)
+          result = cleanup_after_execution(
+            result,
+            start_time,
+            logs,
+            swarm_stop_triggered,
+            has_logging,
+            interrupted: interrupted,
+          )
+          @interrupted_result = result if interrupted
         end
 
         result
       end
 
       # Main execution loop with reprompting support
+      #
+      # Checks for stop requests at the top of each iteration to prevent
+      # unnecessary LLM calls after stop is requested.
       def execution_loop(initial_prompt, logs, start_time)
         current_prompt = initial_prompt
 
         loop do
+          raise InterruptedError, "Swarm execution was interrupted" if @swarm.stop_requested?
+
           lead = @swarm.agents[@swarm.lead_agent]
           response = yield(lead, current_prompt)
 
@@ -197,7 +292,31 @@ module SwarmSDK
       end
 
       # Cleanup after execution (ensure block logic)
-      def cleanup_after_execution(result, start_time, logs, swarm_stop_triggered, has_logging)
+      #
+      # When interrupted, emits agent_stop events for active agents, builds
+      # an interrupted result, and triggers swarm_stop hook with interrupted context.
+      #
+      # @param result [Result, nil] Current execution result
+      # @param start_time [Time] Execution start time
+      # @param logs [Array] Collected logs
+      # @param swarm_stop_triggered [Boolean] Whether swarm_stop hook already fired
+      # @param has_logging [Boolean] Whether logging is enabled
+      # @param interrupted [Boolean] Whether execution was interrupted
+      # @return [Result] Final result (may be replaced with interrupted result)
+      def cleanup_after_execution(result, start_time, logs, swarm_stop_triggered, has_logging, interrupted: false)
+        if interrupted && !swarm_stop_triggered
+          emit_interrupted_agent_events
+          result = build_interrupted_result(logs, start_time)
+
+          # Trigger swarm_stop hook with interrupted result (emits swarm_stop event)
+          begin
+            @swarm.trigger_swarm_stop(result)
+          rescue StandardError => e
+            LogStream.emit_error(e, source: "executor", context: "interrupted_swarm_stop")
+          end
+          swarm_stop_triggered = true
+        end
+
         # Trigger swarm_stop if not already triggered (handles error cases)
         unless swarm_stop_triggered
           @swarm.trigger_swarm_stop_final(result, start_time, logs)
@@ -214,6 +333,43 @@ module SwarmSDK
 
         # Reset logging state for next execution if we set it up
         reset_logging if has_logging
+
+        result
+      end
+
+      # Emit agent_stop events for all agents that were actively executing when interrupted
+      #
+      # @return [void]
+      def emit_interrupted_agent_events
+        @swarm.active_agent_chats.each do |name, _chat|
+          LogStream.emit(
+            type: "agent_stop",
+            agent: name,
+            swarm_id: @swarm.swarm_id,
+            parent_swarm_id: @swarm.parent_swarm_id,
+            finish_reason: "interrupted",
+            content: nil,
+            tool_calls: [],
+            usage: {},
+            metadata: { interrupted: true },
+          )
+        end
+      end
+
+      # Build an interrupted result
+      #
+      # @param logs [Array] Collected logs
+      # @param start_time [Time] Execution start time
+      # @return [Result] Result marked as interrupted
+      def build_interrupted_result(logs, start_time)
+        Result.new(
+          content: nil,
+          agent: @swarm.lead_agent&.to_s || "unknown",
+          error: InterruptedError.new("Swarm execution was interrupted"),
+          logs: logs,
+          duration: Time.now - start_time,
+          metadata: { interrupted: true, finish_reason: "interrupted" },
+        )
       end
 
       # Restore Fiber-local storage to original values (preserves parent context)

data/lib/swarm_sdk/swarm/hook_triggers.rb

@@ -63,6 +63,16 @@ module SwarmSDK
       # @param result [Result] Execution result
       # @return [Hooks::Context] Hook context for swarm_stop event
       def build_swarm_stop_context(result)
+        finish_reason = if @stop_requested
+          "interrupted"
+        elsif result&.error.is_a?(ExecutionTimeoutError)
+          "timeout"
+        elsif result&.success?
+          "finished"
+        else
+          "error"
+        end
+
         Hooks::Context.new(
           event: :swarm_stop,
           agent_name: @lead_agent.to_s,
@@ -79,6 +89,7 @@ module SwarmSDK
             agents_involved: result.agents_involved,
             per_agent_usage: result.per_agent_usage,
             result: result,
+            finish_reason: finish_reason,
             timestamp: Time.now.utc.iso8601,
           },
         )

data/lib/swarm_sdk/swarm/logging_callbacks.rb

@@ -204,6 +204,7 @@ module SwarmSDK
           last_agent: context.metadata[:last_agent],
           content: context.metadata[:content],
           success: context.metadata[:success],
+          finish_reason: context.metadata[:finish_reason] || "finished",
           duration: context.metadata[:duration],
           total_cost: context.metadata[:total_cost],
           total_tokens: context.metadata[:total_tokens],

data/lib/swarm_sdk/swarm/mcp_configurator.rb

@@ -129,6 +129,9 @@ module SwarmSDK
       # @param config [Hash] MCP server configuration
       # @return [RubyLLM::MCP::Client] Initialized MCP client
       def initialize_mcp_client(config)
+        # Configure SSL before creating the client so HTTPX connections use the right options
+        configure_mcp_ssl(config)
+
         # Convert timeout from seconds to milliseconds
         # Use explicit config[:timeout] if provided, otherwise use global default
         timeout_seconds = config[:timeout] || SwarmSDK.config.mcp_request_timeout
@@ -230,6 +233,23 @@ module SwarmSDK
         }
       end
 
+      # Configure SSL options for MCP HTTPX connections
+      #
+      # Sets McpSslPatch.ssl_options based on per-server ssl_verify config
+      # or global SwarmSDK.config.mcp_ssl_verify. Resets the thread-local
+      # connection cache so build_connection picks up the new options.
+      #
+      # @param config [Hash] MCP server configuration
+      # @option config [Boolean] :ssl_verify Override global SSL verify setting
+      # @return [void]
+      def configure_mcp_ssl(config)
+        ssl_verify = config.fetch(:ssl_verify, SwarmSDK.config.mcp_ssl_verify)
+        verify_mode = ssl_verify ? OpenSSL::SSL::VERIFY_PEER : OpenSSL::SSL::VERIFY_NONE
+
+        McpSslPatch.ssl_options = { verify_mode: verify_mode }
+        McpSslPatch.reset_connection!
+      end
+
       # Emit MCP server initialization start event
       #
       # @param agent_name [Symbol] Agent name