swarm_memory 2.1.2 → 2.1.4

data/lib/swarm_sdk/agent/chat_helpers/token_tracking.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module Agent
+    module ChatHelpers
+      # Token usage tracking and context limit management
+      #
+      # Extracted from Chat to reduce class size and centralize token metrics.
+      module TokenTracking
+        # Get context window limit for the current model
+        #
+        # @return [Integer, nil] Maximum context tokens
+        def context_limit
+          return @explicit_context_window if @explicit_context_window
+          return @real_model_info.context_window if @real_model_info&.context_window
+
+          model_context_window
+        rescue StandardError
+          nil
+        end
+
+        # Calculate cumulative input tokens for the conversation
+        #
+        # Gets input_tokens from the most recent assistant message, which represents
+        # the total context size sent to the model (not sum of all messages).
+        #
+        # @return [Integer] Total input tokens used
+        def cumulative_input_tokens
+          find_last_message { |msg| msg.role == :assistant && msg.input_tokens }&.input_tokens || 0
+        end
+
+        # Calculate cumulative output tokens across all assistant messages
+        #
+        # @return [Integer] Total output tokens used
+        def cumulative_output_tokens
+          assistant_messages.sum { |msg| msg.output_tokens || 0 }
+        end
+
+        # Calculate cumulative cached tokens
+        #
+        # @return [Integer] Total cached tokens used
+        def cumulative_cached_tokens
+          assistant_messages.sum { |msg| msg.cached_tokens || 0 }
+        end
+
+        # Calculate cumulative cache creation tokens
+        #
+        # @return [Integer] Total tokens written to cache
+        def cumulative_cache_creation_tokens
+          assistant_messages.sum { |msg| msg.cache_creation_tokens || 0 }
+        end
+
+        # Calculate effective input tokens (excluding cache hits)
+        #
+        # @return [Integer] Actual input tokens charged
+        def effective_input_tokens
+          cumulative_input_tokens - cumulative_cached_tokens
+        end
+
+        # Calculate total tokens used (input + output)
+        #
+        # @return [Integer] Total tokens used
+        def cumulative_total_tokens
+          cumulative_input_tokens + cumulative_output_tokens
+        end
+
+        # Calculate percentage of context window used
+        #
+        # @return [Float] Percentage (0.0 to 100.0)
+        def context_usage_percentage
+          limit = context_limit
+          return 0.0 if limit.nil? || limit.zero?
+
+          (cumulative_total_tokens.to_f / limit * 100).round(2)
+        end
+
+        # Calculate remaining tokens in context window
+        #
+        # @return [Integer, nil] Tokens remaining
+        def tokens_remaining
+          limit = context_limit
+          return if limit.nil?
+
+          limit - cumulative_total_tokens
+        end
+
+        # Compact the conversation history to reduce token usage
+        #
+        # @param options [Hash] Compression options
+        # @return [ContextCompactor::Metrics] Compression statistics
+        def compact_context(**options)
+          compactor = ContextCompactor.new(self, options)
+          compactor.compact
+        end
+      end
+    end
+  end
+end

data/lib/swarm_sdk/agent/context.rb

@@ -30,18 +30,22 @@ module SwarmSDK
       # 60% triggers automatic compression, 80%/90% are informational warnings
       CONTEXT_WARNING_THRESHOLDS = [60, 80, 90].freeze
 
-      # Threshold at which automatic compression is triggered
-      COMPRESSION_THRESHOLD = 60
+      # Backward compatibility alias - use Defaults module for new code
+      COMPRESSION_THRESHOLD = Defaults::Context::COMPRESSION_THRESHOLD_PERCENT
 
-      attr_reader :name, :delegation_tools, :metadata, :warning_thresholds_hit
+      attr_reader :name, :delegation_tools, :metadata, :warning_thresholds_hit, :swarm_id, :parent_swarm_id
 
       # Initialize a new agent context
       #
       # @param name [Symbol, String] Agent name
+      # @param swarm_id [String] Swarm ID for event tracking
+      # @param parent_swarm_id [String, nil] Parent swarm ID (nil for root swarms)
       # @param delegation_tools [Array<String>] Names of tools that are delegations
       # @param metadata [Hash] Optional metadata about the agent
-      def initialize(name:, delegation_tools: [], metadata: {})
+      def initialize(name:, swarm_id:, parent_swarm_id: nil, delegation_tools: [], metadata: {})
         @name = name.to_sym
+        @swarm_id = swarm_id
+        @parent_swarm_id = parent_swarm_id
         @delegation_tools = Set.new(delegation_tools.map(&:to_s))
         @metadata = metadata
         @delegation_call_ids = Set.new

data/lib/swarm_sdk/agent/context_manager.rb

@@ -18,10 +18,16 @@ module SwarmSDK
     class ContextManager
       SYSTEM_REMINDER_REGEX = %r{<system-reminder>.*?</system-reminder>}m
 
+      # Expose compression state for snapshot/restore
+      # NOTE: @compression_applied initializes to nil (not false), only set to true when compression runs
+      attr_reader :compression_applied
+      attr_writer :compression_applied
+
       def initialize
         # Ephemeral content to append to messages for this turn only
         # Format: { message_index => [array of reminder strings] }
         @ephemeral_content = {}
+        # NOTE: @compression_applied is NOT initialized here - starts as nil
       end
 
       # Track ephemeral content to append to a specific message

data/lib/swarm_sdk/agent/definition.rb

@@ -18,11 +18,6 @@ module SwarmSDK
     #     system_prompt: "You build APIs"
     #   })
     class Definition
-      DEFAULT_MODEL = "gpt-5"
-      DEFAULT_PROVIDER = "openai"
-      DEFAULT_TIMEOUT = 300 # 5 minutes - reasoning models can take a while
-      BASE_SYSTEM_PROMPT_PATH = File.expand_path("../prompts/base_system_prompt.md.erb", __dir__)
-
       attr_reader :name,
         :description,
         :model,
@@ -44,13 +39,21 @@ module SwarmSDK
         :agent_permissions,
         :assume_model_exists,
         :hooks,
-        :memory
+        :plugin_configs,
+        :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,
@@ -64,14 +67,14 @@ module SwarmSDK
         end
 
         @description = config[:description]
-        @model = config[:model] || DEFAULT_MODEL
-        @provider = config[:provider] || DEFAULT_PROVIDER
+        @model = config[:model] || Defaults::Agent::MODEL
+        @provider = config[:provider] || Defaults::Agent::PROVIDER
         @base_url = config[:base_url]
         @api_version = config[:api_version]
         @context_window = config[:context_window] # Explicit context window override
         @parameters = config[:parameters] || {}
         @headers = Utils.stringify_keys(config[:headers] || {})
-        @timeout = config[:timeout] || DEFAULT_TIMEOUT
+        @timeout = config[:timeout] || Defaults::Timeouts::AGENT_REQUEST_SECONDS
         @bypass_permissions = config[:bypass_permissions] || false
         @max_concurrent_tools = config[:max_concurrent_tools]
         # Always assume model exists - SwarmSDK validates models separately using models.json
@@ -92,9 +95,12 @@ module SwarmSDK
         # Parse directory first so it can be used in system prompt rendering
         @directory = parse_directory(config[:directory])
 
-        # Parse memory configuration BEFORE building system prompt
-        # (memory prompt needs to be appended if memory is enabled)
-        @memory = parse_memory_config(config[:memory])
+        # Extract plugin configurations (generic bucket for all plugin-specific keys)
+        # This allows plugins to store their config without SDK knowing about them
+        @plugin_configs = extract_plugin_configs(config)
+
+        # 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 +117,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
@@ -121,40 +127,20 @@ module SwarmSDK
         validate!
       end
 
-      # Check if memory is enabled for this agent
+      # Get plugin-specific configuration
       #
-      # @return [Boolean]
-      def memory_enabled?
-        return false if @memory.nil?
-
-        # MemoryConfig object (from DSL)
-        return @memory.enabled? if @memory.respond_to?(:enabled?)
-
-        # Hash (from YAML) - check for directory key
-        if @memory.is_a?(Hash)
-          directory = @memory[:directory] || @memory["directory"]
-          return !directory.nil? && !directory.to_s.strip.empty?
-        end
-
-        false
-      end
-
-      # Parse memory configuration from Hash or MemoryConfig object
+      # Plugins store their configuration in the generic plugin_configs hash.
+      # This allows SDK to remain plugin-agnostic while plugins can store
+      # arbitrary configuration.
+      #
+      # @param plugin_name [Symbol] Plugin name (e.g., :memory)
+      # @return [Object, nil] Plugin configuration or nil if not present
       #
-      # @param memory_config [Hash, Object, nil] Memory configuration
-      # @return [Object, Hash, nil] Memory config (could be MemoryConfig from swarm_memory or Hash)
-      def parse_memory_config(memory_config)
-        return if memory_config.nil?
-
-        # If it's a MemoryConfig object (duck typing - has directory, adapter, mode methods)
-        # return as-is. This could be SwarmMemory::DSL::MemoryConfig or any compatible object.
-        return memory_config if memory_config.respond_to?(:directory) &&
-          memory_config.respond_to?(:adapter) &&
-          memory_config.respond_to?(:enabled?)
-
-        # If it's a hash (from YAML), keep it as a hash
-        # Plugin will create storage adapter based on the hash values
-        memory_config
+      # @example
+      #   agent_definition.plugin_config(:memory)
+      #   # => { directory: "tmp/memory", mode: :researcher }
+      def plugin_config(plugin_name)
+        @plugin_configs[plugin_name.to_sym] || @plugin_configs[plugin_name.to_s]
       end
 
       def to_h
@@ -181,6 +167,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,
@@ -273,141 +260,59 @@ module SwarmSDK
       end
 
       def build_full_system_prompt(custom_prompt)
-        # Build the base prompt based on coding_agent setting
-        prompt = if @coding_agent
-          # Coding agent: include full base prompt
-          rendered_base = render_base_system_prompt
-
-          if custom_prompt && !custom_prompt.strip.empty?
-            "#{rendered_base}\n\n#{custom_prompt}"
-          else
-            rendered_base
-          end
-        elsif default_tools_enabled?
-          # Non-coding agent: optionally include TODO/Scratchpad sections if default tools available
-          non_coding_base = render_non_coding_base_prompt
-
-          if custom_prompt && !custom_prompt.strip.empty?
-            # Prepend TODO/Scratchpad info before custom prompt
-            "#{non_coding_base}\n\n#{custom_prompt}"
-          else
-            # No custom prompt: just return TODO/Scratchpad info
-            non_coding_base
-          end
-        else
-          # No default tools: return only custom prompt
-          (custom_prompt || "").to_s
-        end
-
-        # Append plugin contributions to system prompt
-        plugin_contributions = collect_plugin_prompt_contributions
-        if plugin_contributions.any?
-          combined_contributions = plugin_contributions.join("\n\n")
-          prompt = if prompt && !prompt.strip.empty?
-            "#{prompt}\n\n#{combined_contributions}"
-          else
-            combined_contributions
-          end
-        end
-
-        prompt
-      end
-
-      # Check if default tools are enabled (i.e., not disabled)
-      #
-      # @return [Boolean] True if default tools should be included
-      def default_tools_enabled?
-        @disable_default_tools != true
+        # Delegate to SystemPromptBuilder for all prompt construction logic
+        # This keeps Definition focused on data storage while extracting complex logic
+        SystemPromptBuilder.build(
+          custom_prompt: custom_prompt,
+          coding_agent: @coding_agent,
+          disable_default_tools: @disable_default_tools,
+          directory: @directory,
+          definition: self,
+        )
       end
 
-      def render_base_system_prompt
-        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)
+      def parse_directory(directory_config)
+        directory_config ||= "."
+        File.expand_path(directory_config.to_s)
       end
 
-      # Collect system prompt contributions from all plugins
+      # Extract plugin-specific configuration keys from the config hash
       #
-      # Asks each registered plugin if it wants to contribute to the system prompt.
-      # Plugins can return custom instructions based on their configuration.
+      # Standard SDK keys are filtered out, leaving only plugin-specific keys.
+      # This allows plugins to add their own configuration without SDK modifications.
       #
-      # @return [Array<String>] Array of prompt contributions from plugins
-      def collect_plugin_prompt_contributions
-        contributions = []
-
-        PluginRegistry.all.each do |plugin|
-          # Check if plugin has storage enabled for this agent
-          next unless plugin.storage_enabled?(self)
-
-          # Ask plugin for prompt contribution
-          # Note: storage is not available yet at this point, so we pass nil
-          contribution = plugin.system_prompt_contribution(agent_definition: self, storage: nil)
-          contributions << contribution if contribution && !contribution.strip.empty?
-        end
-
-        contributions
-      end
-
-      def render_non_coding_base_prompt
-        # Simplified base prompt for non-coding agents
-        # Includes environment info, TODO, and Scratchpad tool information
-        # Does not steer towards coding tasks
-        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>
-
-          # 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
-
-      def parse_directory(directory_config)
-        directory_config ||= "."
-        File.expand_path(directory_config.to_s)
+      # @param config [Hash] Full agent configuration
+      # @return [Hash] Plugin-specific configuration (keys not recognized by SDK)
+      def extract_plugin_configs(config)
+        standard_keys = [
+          :name,
+          :description,
+          :model,
+          :provider,
+          :base_url,
+          :api_version,
+          :context_window,
+          :parameters,
+          :headers,
+          :timeout,
+          :bypass_permissions,
+          :max_concurrent_tools,
+          :assume_model_exists,
+          :disable_default_tools,
+          :coding_agent,
+          :directory,
+          :system_prompt,
+          :tools,
+          :delegates_to,
+          :mcp_servers,
+          :hooks,
+          :default_permissions,
+          :permissions,
+          :shared_across_delegations,
+          :directories,
+        ]
+
+        config.reject { |k, _| standard_keys.include?(k.to_sym) }
       end
 
       # Parse tools configuration with permissions support

data/lib/swarm_sdk/agent/llm_instrumentation_middleware.rb

@@ -0,0 +1,182 @@
+# 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
+        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 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
+        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
+      #
+      # @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