swarm_sdk 2.7.13 → 2.7.15

data/lib/swarm_sdk/ruby_llm_patches/openai_thought_signature_patch.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+# Patches RubyLLM::Providers::OpenAI::Tools to preserve thought_signature
+# through the OpenAI-compatible streaming pipeline.
+#
+# Vertex AI Gemini 3 models with "thinking" enabled return a thought_signature
+# in tool call responses via extra_content.google.thought_signature. This must
+# be echoed back in subsequent requests or the API rejects the request with:
+#
+#   "function call is missing a thought_signature"
+#
+# The native Gemini provider handles this correctly, but the OpenAI provider
+# (used for OpenAI-compatible proxies) drops thought_signature in both
+# parse_tool_calls and format_tool_calls. The rest of the pipeline
+# (StreamAccumulator, ToolCall) already supports thought_signature.
+#
+# This patch:
+# - Extracts thought_signature from extra_content during tool call parsing
+# - Echoes thought_signature back in extra_content during serialization
+
+module RubyLLM
+  module Providers
+    class OpenAI
+      module Tools
+        # rubocop:disable Style/ModuleFunction -- required to replace singleton method copy
+
+        module_function
+
+        # Parse tool calls from OpenAI-format response data
+        #
+        # @param tool_calls [Array<Hash>] Raw tool call data from API response
+        # @param parse_arguments [Boolean] Whether to JSON-parse arguments (false during streaming)
+        # @return [Hash{String => ToolCall}, nil] Parsed tool calls keyed by ID
+        def parse_tool_calls(tool_calls, parse_arguments: true)
+          return unless tool_calls&.any?
+
+          tool_calls.to_h do |tc|
+            thought_sig = tc.dig("extra_content", "google", "thought_signature")
+
+            [
+              tc["id"],
+              ToolCall.new(
+                id: tc["id"],
+                name: tc.dig("function", "name"),
+                arguments: if parse_arguments
+                             parse_tool_call_arguments(tc)
+                           else
+                             tc.dig("function", "arguments")
+                           end,
+                thought_signature: thought_sig,
+              ),
+            ]
+          end
+        end
+
+        # Serialize tool calls into OpenAI-format request data
+        #
+        # @param tool_calls [Hash{String => ToolCall}] Tool calls to serialize
+        # @return [Array<Hash>, nil] Serialized tool calls for API request
+        def format_tool_calls(tool_calls)
+          return unless tool_calls&.any?
+
+          tool_calls.map do |_, tc|
+            entry = {
+              id: tc.id,
+              type: "function",
+              function: {
+                name: tc.name,
+                arguments: JSON.generate(tc.arguments),
+              },
+            }
+
+            if tc.thought_signature
+              entry[:extra_content] = { google: { thought_signature: tc.thought_signature } }
+            end
+
+            entry
+          end
+        end
+
+        # Parse tool call arguments from raw hash
+        #
+        # @param tool_call [Hash] Raw tool call hash
+        # @return [Hash] Parsed arguments
+        def parse_tool_call_arguments(tool_call)
+          arguments = tool_call.dig("function", "arguments")
+
+          if arguments.nil? || arguments.empty?
+            {}
+          else
+            JSON.parse(arguments)
+          end
+        end
+        # rubocop:enable Style/ModuleFunction
+      end
+    end
+  end
+end

data/lib/swarm_sdk/ruby_llm_patches/streaming_error_patch.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+# Hardens RubyLLM::Providers::OpenAI::Streaming#parse_streaming_error against
+# non-standard error response shapes returned by OpenAI-compatible proxies
+# (e.g. Gemini via Vertex AI).
+#
+# The upstream implementation assumes `error_data['error']` is always a Hash,
+# but some proxies return a bare String ({"error": "message"}) or an Array
+# top-level, causing TypeError: no implicit conversion of String into Integer.
+#
+# This patch adds type guards while preserving the exact original behavior
+# for well-formed OpenAI error responses.
+#
+# Upstream issue: https://github.com/crmne/ruby_llm/issues/XXX
+
+module RubyLLM
+  module Providers
+    class OpenAI
+      module Streaming
+        # rubocop:disable Style/ModuleFunction -- module_function is required here
+        # to replace both the singleton and instance method copies created by the
+        # original module_function call in upstream RubyLLM. extend self would only
+        # add a delegation layer and not override the existing singleton method.
+
+        module_function
+
+        def parse_streaming_error(data)
+          error_data = JSON.parse(data)
+          return unless error_data.is_a?(Hash)
+
+          error = error_data["error"]
+          return unless error
+
+          # Some proxies return {"error": "message"} instead of {"error": {"type": ..., "message": ...}}
+          return [500, error.to_s] unless error.is_a?(Hash)
+
+          case error["type"]
+          when "server_error"
+            [500, error["message"]]
+          when "rate_limit_exceeded", "insufficient_quota"
+            [429, error["message"]]
+          else
+            [400, error["message"]]
+          end
+        end
+        # rubocop:enable Style/ModuleFunction
+      end
+    end
+  end
+end

data/lib/swarm_sdk/ruby_llm_patches/tool_concurrency_patch.rb

@@ -149,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