swarm_sdk 2.1.2 → 2.2.0

data/lib/swarm_sdk/agent/definition.rb

@@ -44,13 +44,21 @@ module SwarmSDK
         :agent_permissions,
         :assume_model_exists,
         :hooks,
-        :memory
+        :memory,
+        :shared_across_delegations
 
       attr_accessor :bypass_permissions, :max_concurrent_tools
 
       def initialize(name, config = {})
         @name = name.to_sym
 
+        # Validate name doesn't contain '@' (reserved for delegation instances)
+        if @name.to_s.include?("@")
+          raise ConfigurationError,
+            "Agent names cannot contain '@' character (reserved for delegation instance naming). " \
+              "Agent: #{@name}"
+        end
+
         # BREAKING CHANGE: Hard error for plural form
         if config[:directories]
           raise ConfigurationError,
@@ -96,6 +104,9 @@ module SwarmSDK
         # (memory prompt needs to be appended if memory is enabled)
         @memory = parse_memory_config(config[:memory])
 
+        # Delegation isolation mode (default: false = isolated instances per delegation)
+        @shared_across_delegations = config[:shared_across_delegations] || false
+
         # Build system prompt after directory and memory are set
         @system_prompt = build_full_system_prompt(config[:system_prompt])
 
@@ -111,7 +122,7 @@ module SwarmSDK
         # Inject default write restrictions for security
         @tools = inject_default_write_permissions(@tools)
 
-        @delegates_to = Array(config[:delegates_to] || []).map(&:to_sym)
+        @delegates_to = Array(config[:delegates_to] || []).map(&:to_sym).uniq
         @mcp_servers = Array(config[:mcp_servers] || [])
 
         # Parse hooks configuration
@@ -181,6 +192,7 @@ module SwarmSDK
           assume_model_exists: @assume_model_exists,
           max_concurrent_tools: @max_concurrent_tools,
           hooks: @hooks,
+          shared_across_delegations: @shared_across_delegations,
           # Permissions are core SDK functionality (not plugin-specific)
           default_permissions: @default_permissions,
           permissions: @agent_permissions,
@@ -358,7 +370,7 @@ module SwarmSDK
 
       def render_non_coding_base_prompt
         # Simplified base prompt for non-coding agents
-        # Includes environment info, TODO, and Scratchpad tool information
+        # Includes environment info only
         # Does not steer towards coding tasks
         cwd = @directory || Dir.pwd
         platform = RUBY_PLATFORM
@@ -383,25 +395,6 @@ module SwarmSDK
           Platform: #{platform}
           OS Version: #{os_version}
           </env>
-
-          # Task Management
-
-          You have access to the TodoWrite tool to help you manage and plan tasks. Use this tool to track your progress and give visibility into your work.
-
-          When working on multi-step tasks:
-          1. Create a todo list with all known tasks before starting work
-          2. Mark each task as in_progress when you start it
-          3. Mark each task as completed IMMEDIATELY after finishing it
-          4. Complete ALL pending todos before finishing your response
-
-          # Scratchpad Storage
-
-          You have access to Scratchpad tools for storing and retrieving information:
-          - **ScratchpadWrite**: Store detailed outputs, analysis, or results that are too long for direct responses
-          - **ScratchpadRead**: Retrieve previously stored content
-          - **ScratchpadList**: List available scratchpad entries
-
-          Use the scratchpad to share information that would otherwise clutter your responses.
         PROMPT
       end
 

data/lib/swarm_sdk/agent/llm_instrumentation_middleware.rb

@@ -0,0 +1,180 @@
+# 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
+
+        # Emit request event
+        emit_request_event(env, start_time)
+
+        # Execute request
+        @app.call(env).on_complete do |response_env|
+          end_time = Time.now
+          duration = end_time - start_time
+
+          # Emit response event
+          emit_response_event(response_env, start_time, end_time, duration)
+        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,
+          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
+        RubyLLM.logger.error("LLM instrumentation request error: #{e.message}")
+      end
+
+      # Emit response event
+      #
+      # @param env [Faraday::Env] Response environment
+      # @param start_time [Time] Request start time
+      # @param end_time [Time] Request end time
+      # @param duration [Float] Request duration in seconds
+      # @return [void]
+      def emit_response_event(env, start_time, end_time, duration)
+        response_data = {
+          provider: @provider_name,
+          body: parse_body(env.body),
+          duration_seconds: duration.round(3),
+          timestamp: end_time.utc.iso8601,
+        }
+
+        # Extract usage information from response body if available
+        if env.body.is_a?(String) && !env.body.empty?
+          begin
+            parsed = JSON.parse(env.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)
+          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
+        RubyLLM.logger.error("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
+      #
+      # @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 truncated string if not JSON
+        body.to_s[0..1000]
+      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