swarm_sdk 2.7.14 → 3.0.0.alpha1

data/lib/swarm_sdk/agent/llm_instrumentation_middleware.rb

@@ -1,226 +0,0 @@
-# frozen_string_literal: true
-
-module SwarmSDK
-  module Agent
-    # Faraday middleware for capturing LLM API requests and responses
-    #
-    # This middleware intercepts HTTP calls to LLM providers and emits
-    # structured events via LogStream for logging and monitoring.
-    #
-    # Events emitted:
-    # - llm_api_request: Before sending request to LLM API
-    # - llm_api_response: After receiving response from LLM API
-    #
-    # The middleware is injected at runtime into the provider's Faraday
-    # connection stack (see Agent::Chat#inject_llm_instrumentation).
-    class LLMInstrumentationMiddleware < Faraday::Middleware
-      # Initialize middleware
-      #
-      # @param app [Faraday::Connection] Faraday app
-      # @param on_request [Proc] Callback for request events
-      # @param on_response [Proc] Callback for response events
-      # @param provider_name [String] Provider name for logging
-      def initialize(app, on_request:, on_response:, provider_name:)
-        super(app)
-        @on_request = on_request
-        @on_response = on_response
-        @provider_name = provider_name
-      end
-
-      # Intercept HTTP call
-      #
-      # @param env [Faraday::Env] Request environment
-      # @return [Faraday::Response] HTTP response
-      def call(env)
-        start_time = Time.now
-        accumulated_raw_chunks = []
-
-        # Emit request event
-        emit_request_event(env, start_time)
-
-        # Wrap existing on_data to capture raw SSE chunks for streaming
-        if env.request&.on_data
-          original_on_data = env.request.on_data
-          env.request.on_data = proc do |chunk, bytes, response_env|
-            # Capture raw chunk BEFORE RubyLLM processes it
-            accumulated_raw_chunks << chunk
-            # Call original handler (RubyLLM's stream processing)
-            original_on_data.call(chunk, bytes, response_env)
-          end
-        end
-
-        # Execute request
-        @app.call(env).on_complete do |response_env|
-          end_time = Time.now
-
-          # Determine if this was a streaming request based on whether chunks were accumulated
-          # This is more reliable than parsing response content
-          is_streaming = accumulated_raw_chunks.any?
-
-          # For streaming: use accumulated raw SSE chunks
-          # For non-streaming: use response body
-          raw_body = is_streaming ? accumulated_raw_chunks.join : response_env.body
-
-          # Store SSE body in Fiber-local for citation extraction
-          # This allows append_citations_to_content to access the full SSE body
-          # even though response.body is empty for streaming responses
-          Fiber[:last_sse_body] = raw_body if is_streaming
-
-          # Emit response event
-          timing = { start_time: start_time, end_time: end_time, duration: end_time - start_time }
-          emit_response_event(response_env, timing, raw_body, is_streaming)
-        end
-      end
-
-      private
-
-      # Emit request event
-      #
-      # @param env [Faraday::Env] Request environment
-      # @param timestamp [Time] Request timestamp
-      # @return [void]
-      def emit_request_event(env, timestamp)
-        request_data = {
-          provider: @provider_name,
-          url: env.url.to_s,
-          body: parse_body(env.body),
-          timestamp: timestamp.utc.iso8601,
-        }
-
-        @on_request.call(request_data)
-      rescue StandardError => e
-        # Don't let logging errors break the request
-        LogStream.emit_error(e, source: "llm_instrumentation_middleware", context: "emit_request_event", provider: @provider_name)
-        RubyLLM.logger.debug("LLM instrumentation request error: #{e.message}")
-      end
-
-      # Emit response event
-      #
-      # @param env [Faraday::Env] Response environment
-      # @param timing [Hash] Timing information with :start_time, :end_time, :duration keys
-      # @param raw_body [String, nil] Raw response body (SSE stream for streaming, JSON for non-streaming)
-      # @param streaming [Boolean] Whether this was a streaming response (determined by chunk accumulation)
-      # @return [void]
-      def emit_response_event(env, timing, raw_body, streaming)
-        response_data = {
-          provider: @provider_name,
-          body: parse_body(raw_body),
-          streaming: streaming,
-          duration_seconds: timing[:duration].round(3),
-          timestamp: timing[:end_time].utc.iso8601,
-          status: env.status,
-        }
-
-        # Extract usage information from response body if available
-        if raw_body.is_a?(String) && !raw_body.empty?
-          begin
-            if streaming
-              # For streaming, parse the LAST SSE event which contains usage
-              # Skip "[DONE]" marker and find the last actual data event
-              last_data_line = raw_body.split("\n").reverse.find { |l| l.start_with?("data:") && !l.include?("[DONE]") }
-              if last_data_line
-                parsed = JSON.parse(last_data_line.sub(/^data:\s*/, ""))
-                response_data[:usage] = extract_usage(parsed) if parsed.is_a?(Hash)
-                response_data[:model] = parsed["model"] if parsed.is_a?(Hash)
-              end
-            else
-              # For non-streaming, parse the full JSON response
-              parsed = JSON.parse(raw_body)
-              response_data[:usage] = extract_usage(parsed) if parsed.is_a?(Hash)
-              response_data[:model] = parsed["model"] if parsed.is_a?(Hash)
-              response_data[:finish_reason] = extract_finish_reason(parsed) if parsed.is_a?(Hash)
-            end
-          rescue JSON::ParserError
-            # Not JSON, skip usage extraction
-          end
-        end
-
-        @on_response.call(response_data)
-      rescue StandardError => e
-        # Don't let logging errors break the response
-        LogStream.emit_error(e, source: "llm_instrumentation_middleware", context: "emit_response_event", provider: @provider_name)
-        RubyLLM.logger.debug("LLM instrumentation response error: #{e.message}")
-      end
-
-      # Sanitize headers by removing sensitive data
-      #
-      # @param headers [Hash] HTTP headers
-      # @return [Hash] Sanitized headers
-      def sanitize_headers(headers)
-        return {} unless headers
-
-        headers.transform_keys(&:to_s).transform_values do |value|
-          # Redact authorization headers
-          if value.to_s.match?(/bearer|token|key/i)
-            "[REDACTED]"
-          else
-            value.to_s
-          end
-        end
-      rescue StandardError
-        {}
-      end
-
-      # Parse request/response body
-      #
-      # For requests: returns parsed JSON hash
-      # For responses: returns full body (JSON parsed or raw string for SSE)
-      #
-      # @param body [String, Hash, nil] HTTP body
-      # @return [Hash, String, nil] Parsed body
-      def parse_body(body)
-        return if body.nil? || body == ""
-
-        # Already parsed
-        return body if body.is_a?(Hash)
-
-        # Try to parse JSON
-        JSON.parse(body)
-      rescue JSON::ParserError
-        # Return full body for SSE/non-JSON responses
-        # Don't truncate - let consumers decide how to handle large bodies
-        body.to_s
-      rescue StandardError
-        nil
-      end
-
-      # Extract usage statistics from response
-      #
-      # Handles different provider formats (OpenAI, Anthropic, etc.)
-      #
-      # @param parsed [Hash] Parsed response body
-      # @return [Hash, nil] Usage statistics
-      def extract_usage(parsed)
-        usage = parsed["usage"] || parsed.dig("usage")
-        return unless usage
-
-        {
-          input_tokens: usage["input_tokens"] || usage["prompt_tokens"],
-          output_tokens: usage["output_tokens"] || usage["completion_tokens"],
-          total_tokens: usage["total_tokens"],
-        }.compact
-      rescue StandardError
-        nil
-      end
-
-      # Extract finish reason from response
-      #
-      # Handles different provider formats
-      #
-      # @param parsed [Hash] Parsed response body
-      # @return [String, nil] Finish reason
-      def extract_finish_reason(parsed)
-        # Anthropic format
-        return parsed["stop_reason"] if parsed["stop_reason"]
-
-        # OpenAI format
-        choices = parsed["choices"]
-        return unless choices&.is_a?(Array) && !choices.empty?
-
-        choices.first["finish_reason"]
-      rescue StandardError
-        nil
-      end
-    end
-  end
-end

data/lib/swarm_sdk/agent/system_prompt_builder.rb

@@ -1,173 +0,0 @@
-# frozen_string_literal: true
-
-module SwarmSDK
-  module Agent
-    # Builds system prompts for agents
-    #
-    # This class encapsulates all system prompt construction logic, including:
-    # - Base system prompt rendering (for coding agents)
-    # - Non-coding base prompt rendering
-    # - Plugin prompt contribution collection
-    # - Combining base and custom prompts
-    #
-    # ## Safety Note for SwarmMemory Integration
-    #
-    # This is an INTERNAL helper that receives Definition attributes as input.
-    # Definition remains the single source of truth with all instance variables.
-    # SwarmMemory uses `agent_definition.instance_eval { binding }` for ERB templating,
-    # which requires all properties to be on Definition object. This helper is safe
-    # because it doesn't affect Definition's structure - it only extracts logic.
-    class SystemPromptBuilder
-      BASE_SYSTEM_PROMPT_PATH = File.expand_path("../prompts/base_system_prompt.md.erb", __dir__)
-
-      class << self
-        # Build the complete system prompt for an agent
-        #
-        # @param custom_prompt [String, nil] Custom system prompt from configuration
-        # @param coding_agent [Boolean] Whether agent is configured for coding tasks
-        # @param disable_default_tools [Boolean, Array, nil] Default tools disable configuration
-        # @param directory [String] Agent's working directory
-        # @param definition [Definition] Full definition for plugin contributions
-        # @param disable_environment_info [Boolean] Whether to omit environment info from prompt
-        # @return [String] Complete system prompt
-        def build(custom_prompt:, coding_agent:, disable_default_tools:, directory:, definition:,
-          disable_environment_info: false)
-          new(
-            custom_prompt: custom_prompt,
-            coding_agent: coding_agent,
-            disable_default_tools: disable_default_tools,
-            directory: directory,
-            definition: definition,
-            disable_environment_info: disable_environment_info,
-          ).build
-        end
-      end
-
-      def initialize(custom_prompt:, coding_agent:, disable_default_tools:, directory:, definition:,
-        disable_environment_info: false)
-        @custom_prompt = custom_prompt
-        @coding_agent = coding_agent
-        @disable_default_tools = disable_default_tools
-        @directory = directory
-        @definition = definition
-        @disable_environment_info = disable_environment_info
-      end
-
-      def build
-        prompt = base_prompt_section
-        prompt = append_plugin_contributions(prompt)
-        prompt
-      end
-
-      private
-
-      def base_prompt_section
-        if @coding_agent
-          build_coding_agent_prompt
-        elsif default_tools_enabled?
-          build_non_coding_agent_prompt
-        else
-          (@custom_prompt || "").to_s
-        end
-      end
-
-      def build_coding_agent_prompt
-        rendered_base = render_base_system_prompt
-
-        if @custom_prompt && !@custom_prompt.strip.empty?
-          "#{rendered_base}\n\n#{@custom_prompt}"
-        else
-          rendered_base
-        end
-      end
-
-      def build_non_coding_agent_prompt
-        non_coding_base = render_non_coding_base_prompt
-
-        if @custom_prompt && !@custom_prompt.strip.empty?
-          if non_coding_base.empty?
-            @custom_prompt.to_s
-          else
-            "#{non_coding_base}\n\n#{@custom_prompt}"
-          end
-        else
-          non_coding_base
-        end
-      end
-
-      def default_tools_enabled?
-        @disable_default_tools != true
-      end
-
-      def render_base_system_prompt
-        disable_environment_info = @disable_environment_info
-        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 render_non_coding_base_prompt
-        return "" if @disable_environment_info
-
-        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")
-
-        <<~PROMPT.strip
-          # Today's date
-
-          <today-date>
-          #{date}
-          #</today-date>
-
-          # Current Environment
-
-          <env>
-          Working directory: #{cwd}
-          Platform: #{platform}
-          OS Version: #{os_version}
-          </env>
-        PROMPT
-      end
-
-      def append_plugin_contributions(prompt)
-        contributions = collect_plugin_prompt_contributions
-        return prompt if contributions.empty?
-
-        combined_contributions = contributions.join("\n\n")
-
-        if prompt && !prompt.strip.empty?
-          "#{prompt}\n\n#{combined_contributions}"
-        else
-          combined_contributions
-        end
-      end
-
-      def collect_plugin_prompt_contributions
-        contributions = []
-
-        PluginRegistry.all.each do |plugin|
-          next unless plugin.memory_configured?(@definition)
-
-          contribution = plugin.system_prompt_contribution(agent_definition: @definition, storage: nil)
-          contributions << contribution if contribution && !contribution.strip.empty?
-        end
-
-        contributions
-      end
-    end
-  end
-end

data/lib/swarm_sdk/agent/tool_registry.rb

@@ -1,189 +0,0 @@
-# frozen_string_literal: true
-
-module SwarmSDK
-  module Agent
-    # Per-agent tool registry managing available and active tools
-    #
-    # ## Architecture
-    #
-    # - **Available tools**: All tool instances the agent CAN use (registry)
-    # - **Active tools**: Subset sent to LLM based on skill state
-    #
-    # ## Thread Safety
-    #
-    # Registry access is protected by Async::Semaphore for fiber-safe operations.
-    #
-    # @example Registering tools
-    #   registry = ToolRegistry.new
-    #   registry.register(Read.new, source: :builtin)
-    #   registry.register(delegate_tool, source: :delegation, metadata: { delegate_name: :backend })
-    #
-    # @example Getting active tools (no skill)
-    #   active = registry.active_tools(skill_state: nil)
-    #   # Returns ALL available tools
-    #
-    # @example Getting active tools (with skill)
-    #   skill_state = SkillState.new(  # From SwarmMemory plugin
-    #     file_path: "skill/audit.md",
-    #     tools: ["Read", "Grep"],
-    #     permissions: { "Bash" => { deny_commands: ["rm"] } }
-    #   )
-    #   active = registry.active_tools(skill_state: skill_state)
-    #   # Returns: skill's tools + non-removable tools
-    class ToolRegistry
-      # Tool metadata stored in registry
-      #
-      # @!attribute instance [r] Tool instance (possibly wrapped with permissions)
-      # @!attribute base_instance [r] Unwrapped tool instance (for skill permission override)
-      # @!attribute removable [r] Can be deactivated by skills
-      # @!attribute source [r] Tool source (:builtin, :delegation, :mcp, :plugin, :custom)
-      # @!attribute metadata [r] Source-specific metadata
-      ToolEntry = Data.define(:instance, :base_instance, :removable, :source, :metadata)
-
-      def initialize
-        @available_tools = {} # String name => ToolEntry
-        @mutex = Async::Semaphore.new(1) # Fiber-safe mutex
-      end
-
-      # Register a tool in the available tools registry
-      #
-      # @param tool [RubyLLM::Tool] Tool instance (possibly wrapped)
-      # @param base_tool [RubyLLM::Tool, nil] Unwrapped instance (for permission override)
-      # @param source [Symbol] Tool source (:builtin, :delegation, :mcp, :plugin, :custom)
-      # @param metadata [Hash] Source-specific metadata (server_name, plugin_name, etc.)
-      # @return [void]
-      #
-      # @example Register builtin tool
-      #   registry.register(Read.new, source: :builtin)
-      #
-      # @example Register delegation tool
-      #   registry.register(delegate_tool, source: :delegation, metadata: { delegate_name: :backend })
-      #
-      # @example Register MCP tool
-      #   registry.register(mcp_tool, source: :mcp, metadata: { server_name: "codebase" })
-      #
-      # @example Register with permission wrapper
-      #   wrapped_tool = PermissionWrapper.new(base_tool, permissions)
-      #   registry.register(wrapped_tool, base_tool: base_tool, source: :builtin)
-      def register(tool, base_tool: nil, source:, metadata: {})
-        @mutex.acquire do
-          # Infer removability from tool class
-          removable = tool.respond_to?(:removable?) ? tool.removable? : true
-
-          @available_tools[tool.name] = ToolEntry.new(
-            instance: tool,
-            base_instance: base_tool || tool, # If no base, use same instance
-            removable: removable,
-            source: source,
-            metadata: metadata,
-          )
-        end
-      end
-
-      # Unregister a tool (for testing/cleanup)
-      #
-      # @param name [String, Symbol] Tool name
-      # @return [ToolEntry, nil] Removed entry
-      def unregister(name)
-        @mutex.acquire do
-          @available_tools.delete(name.to_s)
-        end
-      end
-
-      # Get active tools based on skill state
-      #
-      # Returns Hash of tool instances ready for RubyLLM::Chat.
-      #
-      # Logic:
-      # - If skill_state is nil: Return ALL available tools
-      # - If skill_state restricts tools: Return skill's tools + non-removable tools
-      # - Skill permissions are applied during activation (wrapping base_instance)
-      #
-      # @param skill_state [Object, nil] Skill state object (from plugin), or nil for all
-      # @param tool_configurator [ToolConfigurator, nil] For permission wrapping
-      # @param agent_definition [Agent::Definition, nil] For permission wrapping
-      # @return [Hash{String => RubyLLM::Tool}] name => instance mapping
-      #
-      # @example No skill loaded - all tools
-      #   registry.active_tools(skill_state: nil)
-      #   # => { "Read" => <Read>, "WorkWithBackend" => <Delegate>, ... }
-      #
-      # @example Skill loaded with focused toolset
-      #   registry.active_tools(skill_state: skill_state)
-      #   # => { "Read" => <Read>, "WorkWithBackend" => <Delegate>, "Think" => <Think>, "MemoryRead" => <MemoryRead> }
-      #   # Includes: requested tools + non-removable tools
-      def active_tools(skill_state: nil, tool_configurator: nil, agent_definition: nil)
-        @mutex.acquire do
-          result = if skill_state&.restricts_tools?
-            # Skill loaded with tool restriction - only skill's tools + non-removable
-            filtered = {}
-
-            # Always include non-removable tools (use wrapped instance)
-            @available_tools.each do |name, entry|
-              filtered[name] = entry.instance unless entry.removable
-            end
-
-            # Add requested tools from skill
-            skill_state.tools.each do |name|
-              entry = @available_tools[name.to_s]
-              next unless entry
-
-              # Check if skill has custom permissions for this tool
-              skill_permissions = skill_state.permissions_for(name)
-
-              if skill_permissions && tool_configurator && agent_definition
-                # Skill overrides permissions - wrap the BASE instance
-                wrapped = tool_configurator.wrap_tool_with_permissions(
-                  entry.base_instance,
-                  skill_permissions,
-                  agent_definition,
-                )
-                filtered[name.to_s] = wrapped
-              else
-                # No skill permission override - use registered instance
-                filtered[name.to_s] = entry.instance
-              end
-            end
-
-            filtered
-          else
-            # No skill OR skill doesn't restrict tools - all available tools
-            @available_tools.transform_values(&:instance)
-          end
-
-          result
-        end
-      end
-
-      # Check if tool exists in registry
-      #
-      # @param name [String, Symbol] Tool name
-      # @return [Boolean]
-      def has_tool?(name)
-        @available_tools.key?(name.to_s)
-      end
-
-      # Get all available tool names
-      #
-      # @return [Array<String>]
-      def tool_names
-        @available_tools.keys
-      end
-
-      # Get tool entry with metadata
-      #
-      # @param name [String, Symbol] Tool name
-      # @return [ToolEntry, nil]
-      def get(name)
-        @available_tools[name.to_s]
-      end
-
-      # Get all non-removable tool names
-      #
-      # @return [Array<String>]
-      def non_removable_tool_names
-        @available_tools.select { |_name, entry| !entry.removable }.keys
-      end
-    end
-  end
-end