swarm_sdk 2.7.5 → 2.7.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6aaba8cabb5957715e88ee02e40e9492fe3546791c806d1ddaff95e967f77aba
-  data.tar.gz: 752d15e6e69bb1a9941212d1c33622d678dcc0dc734b88b77a845c7fca4e982b
+  metadata.gz: b83fd113813e0667b02d12c5ef6b9f4d47c134afa0665e2b6e482a6c9d3dacd7
+  data.tar.gz: 8a758e06817af7690c21fc446597b0e1a91b876643d20a4a111a62bc953d3d5e
 SHA512:
-  metadata.gz: 36532a008bbb328cddf60bca55d7d8e210b2c0701ca546190164a16067d3878e26c6c4a6d347e9f262669c34289bad7ac0ddd714062a6d4ab9807e0ef5fd9dc5
-  data.tar.gz: e7e512794d27d5bd378ea1c96e66f18683cbab8c95e3820672bd74174e0fd5963894958a61aa2e7cf40485c908a7a7adf6a7cbda9d7bfdd480ccd0c3156e4d15
+  metadata.gz: 5bfcfaf82ca105e6b1e1f04e009c703b641c25af6797ccd72c945a0c8dbbfbe60a0d783fc9e8d43322bbefac95b16123c4e7232c4ac9e1850a770d1120568344
+  data.tar.gz: 0aa16f8d6ebe0fd2acb4cb52baba570000c82c4607d015d3a4569d671f9743cb1199edd80953002b8dc0fb673fb464ebfc2d5d0c645f3afb50258c7451281304

data/lib/swarm_sdk/swarm/mcp_configurator.rb

@@ -45,17 +45,23 @@ module SwarmSDK
         Swarm.apply_mcp_logging_configuration
 
         mcp_server_configs.each do |server_config|
+          tools_config = server_config[:tools]
+          mode = tools_config.nil? ? :discovery : :optimized
+
+          # Emit event before initialization
+          emit_mcp_init_start(agent_name, server_config, mode)
+
           client = initialize_mcp_client(server_config)
 
           # Store client for cleanup
           @mcp_clients[agent_name] << client
 
-          tools_config = server_config[:tools]
-
           if tools_config.nil?
             # Discovery mode: Fetch all tools from server (calls tools/list)
             # client.tools returns RubyLLM::Tool instances (already wrapped by internal Coordinator)
             all_tools = client.tools
+            tool_names = all_tools.map { |t| t.respond_to?(:name) ? t.name : t.to_s }
+
             all_tools.each do |tool|
               chat.tool_registry.register(
                 tool,
@@ -63,14 +69,20 @@ module SwarmSDK
                 metadata: { server_name: server_config[:name] },
               )
             end
+
+            # Emit completion event for discovery mode
+            emit_mcp_init_complete(agent_name, server_config, mode, all_tools.size, tool_names)
             RubyLLM.logger.debug("SwarmSDK: Discovered and registered #{all_tools.size} tools from MCP server '#{server_config[:name]}'")
           else
             # Optimized mode: Create tool stubs without tools/list RPC (Plan 025)
             # Use client directly (it has internal coordinator)
+            tool_names = tools_config.map(&:to_s)
+
             tools_config.each do |tool_name|
               stub = Tools::McpToolStub.new(
                 client: client,
                 name: tool_name.to_s,
+                server_name: server_config[:name],
               )
               chat.tool_registry.register(
                 stub,
@@ -78,6 +90,9 @@ module SwarmSDK
                 metadata: { server_name: server_config[:name] },
               )
             end
+
+            # Emit completion event for optimized mode
+            emit_mcp_init_complete(agent_name, server_config, mode, tools_config.size, tool_names)
             RubyLLM.logger.debug("SwarmSDK: Registered #{tools_config.size} tool stubs from MCP server '#{server_config[:name]}' (lazy schema)")
           end
         rescue StandardError => e
@@ -187,6 +202,42 @@ module SwarmSDK
 
         streamable_config
       end
+
+      # Emit MCP server initialization start event
+      #
+      # @param agent_name [Symbol] Agent name
+      # @param server_config [Hash] MCP server configuration
+      # @param mode [Symbol] Initialization mode (:discovery or :optimized)
+      # @return [void]
+      def emit_mcp_init_start(agent_name, server_config, mode)
+        LogStream.emit(
+          type: "mcp_server_init_start",
+          agent: agent_name,
+          server_name: server_config[:name],
+          transport_type: server_config[:type],
+          mode: mode,
+        )
+      end
+
+      # Emit MCP server initialization complete event
+      #
+      # @param agent_name [Symbol] Agent name
+      # @param server_config [Hash] MCP server configuration
+      # @param mode [Symbol] Initialization mode (:discovery or :optimized)
+      # @param tool_count [Integer] Number of tools registered
+      # @param tool_names [Array<String>] Names of registered tools
+      # @return [void]
+      def emit_mcp_init_complete(agent_name, server_config, mode, tool_count, tool_names)
+        LogStream.emit(
+          type: "mcp_server_init_complete",
+          agent: agent_name,
+          server_name: server_config[:name],
+          transport_type: server_config[:type],
+          mode: mode,
+          tool_count: tool_count,
+          tools: tool_names,
+        )
+      end
     end
   end
 end

data/lib/swarm_sdk/tools/image_extractors/pdf_image_extractor.rb

@@ -4,8 +4,10 @@ module SwarmSDK
   module Tools
     module ImageExtractors
       # Extracts images from PDF documents
-      # Supports JPEG (DCTDecode), FlateDecode, and LZWDecode formats
-      # Converts non-JPEG images to TIFF format
+      # Only extracts JPEG images (DCTDecode format) which are LLM API compatible
+      # Non-JPEG images (FlateDecode, LZWDecode) are skipped because they would
+      # require TIFF format which is not supported by LLM APIs
+      # Supported LLM image formats: ['png', 'jpeg', 'gif', 'webp']
       class PdfImageExtractor
         class << self
           # Extract all images from a PDF document
@@ -65,11 +67,13 @@ module SwarmSDK
 
             case filter
             when :DCTDecode
-              # JPEG images can be saved directly
+              # JPEG images can be saved directly - LLM API compatible
               save_jpeg(stream, page_number, name, temp_dir)
             when :FlateDecode, :LZWDecode, nil
-              # Raw or compressed formats - save as TIFF
-              save_as_tiff(stream, page_number, name, temp_dir)
+              # Skip non-JPEG images to avoid TIFF format (not supported by LLM APIs)
+              # LLM APIs only support: ['png', 'jpeg', 'gif', 'webp']
+              # These images would require TIFF conversion which causes API errors
+              nil
             end
             # Unsupported formats return nil
           rescue StandardError

data/lib/swarm_sdk/tools/mcp_tool_stub.rb

@@ -33,22 +33,24 @@ module SwarmSDK
     class McpToolStub < Base
       removable true # MCP tools can be controlled by skills
 
-      attr_reader :name, :client
+      attr_reader :name, :client, :server_name
 
       # Create a new MCP tool stub
       #
       # @param client [RubyLLM::MCP::Client] MCP client instance
       # @param name [String] Tool name
+      # @param server_name [String, nil] MCP server name for error context
       # @param description [String, nil] Tool description (optional, fetched if nil)
       # @param schema [Hash, nil] Tool input schema (optional, fetched if nil)
       #
       # @example Minimal stub (lazy description + schema)
-      #   McpToolStub.new(client: client, name: "search")
+      #   McpToolStub.new(client: client, name: "search", server_name: "codebase")
       #
       # @example With description (lazy schema only)
       #   McpToolStub.new(
       #     client: client,
       #     name: "search",
+      #     server_name: "codebase",
       #     description: "Search the codebase"
       #   )
       #
@@ -56,14 +58,16 @@ module SwarmSDK
       #   McpToolStub.new(
       #     client: client,
       #     name: "search",
+      #     server_name: "codebase",
       #     description: "Search the codebase",
       #     schema: { type: "object", properties: {...} }
       #   )
-      def initialize(client:, name:, description: nil, schema: nil)
+      def initialize(client:, name:, server_name: nil, description: nil, schema: nil)
         super()
         @client = client
         @name = name
         @mcp_name = name
+        @server_name = server_name || "unknown"
         @description = description || "MCP tool: #{name}"
         @input_schema = schema
         @schema_loaded = !schema.nil?
@@ -93,6 +97,9 @@ module SwarmSDK
       #
       # @param params [Hash] Tool parameters
       # @return [String, Hash] Tool result content or error hash
+      # @raise [MCPTimeoutError] When the MCP server times out
+      # @raise [MCPTransportError] When there's a transport-level error
+      # @raise [MCPError] When any other MCP error occurs
       def execute(**params)
         # Use client.call_tool (client has internal coordinator)
         result = @client.call_tool(
@@ -102,6 +109,23 @@ module SwarmSDK
 
         # client.call_tool returns the result content directly
         result
+      rescue RubyLLM::MCP::Errors::TimeoutError => e
+        raise MCPTimeoutError, format_mcp_error(
+          "MCP request timed out",
+          original_message: e.message,
+          request_id: e.request_id,
+        )
+      rescue RubyLLM::MCP::Errors::TransportError => e
+        raise MCPTransportError, format_mcp_error(
+          "MCP transport error",
+          original_message: e.message,
+          code: e.code,
+        )
+      rescue RubyLLM::MCP::Errors::BaseError => e
+        raise MCPError, format_mcp_error(
+          "MCP error",
+          original_message: e.message,
+        )
       end
 
       private
@@ -112,6 +136,9 @@ module SwarmSDK
       # Multiple concurrent fibers will only trigger one fetch.
       #
       # @return [void]
+      # @raise [MCPTimeoutError] When the MCP server times out during schema fetch
+      # @raise [MCPTransportError] When there's a transport-level error
+      # @raise [MCPError] When any other MCP error occurs
       def ensure_schema_loaded!
         return if @schema_loaded
 
@@ -131,6 +158,40 @@ module SwarmSDK
 
           @schema_loaded = true
         end
+      rescue RubyLLM::MCP::Errors::TimeoutError => e
+        raise MCPTimeoutError, format_mcp_error(
+          "MCP schema fetch timed out",
+          original_message: e.message,
+          request_id: e.request_id,
+        )
+      rescue RubyLLM::MCP::Errors::TransportError => e
+        raise MCPTransportError, format_mcp_error(
+          "MCP transport error during schema fetch",
+          original_message: e.message,
+          code: e.code,
+        )
+      rescue RubyLLM::MCP::Errors::BaseError => e
+        raise MCPError, format_mcp_error(
+          "MCP error during schema fetch",
+          original_message: e.message,
+        )
+      end
+
+      # Format MCP error message with contextual information
+      #
+      # @param prefix [String] Error message prefix
+      # @param original_message [String] Original error message from RubyLLM::MCP
+      # @param request_id [String, nil] MCP request ID (for timeout errors)
+      # @param code [Integer, nil] HTTP status code (for transport errors)
+      # @return [String] Formatted error message with full context
+      def format_mcp_error(prefix, original_message:, request_id: nil, code: nil)
+        parts = [prefix]
+        parts << "[server: #{@server_name}]"
+        parts << "[tool: #{@mcp_name}]"
+        parts << "[request_id: #{request_id}]" if request_id
+        parts << "[code: #{code}]" if code
+        parts << "- #{original_message}"
+        parts.join(" ")
       end
     end
   end

data/lib/swarm_sdk/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SwarmSDK
-  VERSION = "2.7.5"
+  VERSION = "2.7.7"
 end

data/lib/swarm_sdk.rb

@@ -71,6 +71,15 @@ module SwarmSDK
   # Raised when agent turn exceeds turn_timeout
   class TurnTimeoutError < TimeoutError; end
 
+  # Base class for MCP-related errors (provides context about server/tool)
+  class MCPError < Error; end
+
+  # Raised when MCP request times out
+  class MCPTimeoutError < MCPError; end
+
+  # Raised when MCP transport fails (connection, HTTP errors)
+  class MCPTransportError < MCPError; end
+
   class << self
     # Get the global configuration instance
     #

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: swarm_sdk
 version: !ruby/object:Gem::Version
-  version: 2.7.5
+  version: 2.7.7
 platform: ruby
 authors:
 - Paulo Arruda