swarm_sdk 2.2.0 → 2.3.0

data/lib/swarm_sdk/context_compactor.rb

@@ -58,7 +58,7 @@ module SwarmSDK
     # @return [ContextCompactor::Metrics] Compression metrics
     def compact
       start_time = Time.now
-      original_messages = @chat.messages.dup
+      original_messages = @chat.messages
 
       # Emit compression_started event
       LogStream.emit(
@@ -308,7 +308,8 @@ module SwarmSDK
       response.content
     rescue StandardError => e
       # If summarization fails, create a simple fallback summary
-      RubyLLM.logger.warn("ContextCompactor: Summarization failed: #{e.message}")
+      LogStream.emit_error(e, source: "context_compactor", context: "generate_summary", agent: @agent_name)
+      RubyLLM.logger.debug("ContextCompactor: Summarization failed: #{e.message}")
 
       <<~FALLBACK
         ## Summary
@@ -322,19 +323,13 @@ module SwarmSDK
 
     # Replace messages in the chat
     #
-    # RubyLLM::Chat doesn't have a public API for replacing all messages,
-    # so we need to work with the internal messages array.
+    # Delegates to the Chat's replace_messages method which provides
+    # a safe abstraction over the internal message array.
     #
     # @param new_messages [Array<RubyLLM::Message>] New message array
     # @return [void]
     def replace_messages(new_messages)
-      # Clear existing messages
-      @chat.messages.clear
-
-      # Add new messages
-      new_messages.each do |msg|
-        @chat.messages << msg
-      end
+      @chat.replace_messages(new_messages)
     end
   end
 end

data/lib/swarm_sdk/context_management/builder.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module ContextManagement
+    # DSL for defining context management handlers
+    #
+    # This builder provides a clean, idiomatic way to register handlers for
+    # context warning thresholds. Handlers receive a rich context object
+    # with message manipulation methods.
+    #
+    # @example Basic usage
+    #   context_management do
+    #     on :warning_60 do |ctx|
+    #       ctx.compress_tool_results(keep_recent: 10)
+    #     end
+    #
+    #     on :warning_80 do |ctx|
+    #       ctx.prune_old_messages(keep_recent: 20)
+    #     end
+    #   end
+    #
+    # @example Progressive compression
+    #   context_management do
+    #     on :warning_60 do |ctx|
+    #       ctx.compress_tool_results(keep_recent: 15, truncate_to: 500)
+    #     end
+    #
+    #     on :warning_80 do |ctx|
+    #       ctx.prune_old_messages(keep_recent: 30)
+    #       ctx.compress_tool_results(keep_recent: 5, truncate_to: 200)
+    #     end
+    #
+    #     on :warning_90 do |ctx|
+    #       ctx.log_action("emergency_pruning", tokens_remaining: ctx.tokens_remaining)
+    #       ctx.prune_old_messages(keep_recent: 15)
+    #     end
+    #   end
+    class Builder
+      # Map semantic event names to threshold percentages
+      EVENT_MAP = {
+        warning_60: 60,
+        warning_80: 80,
+        warning_90: 90,
+      }.freeze
+
+      def initialize
+        @handlers = {} # { threshold => block }
+      end
+
+      # Register a handler for a context warning threshold
+      #
+      # Handlers take full responsibility for managing context at their threshold.
+      # When a handler is registered for a threshold, automatic compression is disabled
+      # for that threshold.
+      #
+      # @param event [Symbol] Event name (:warning_60, :warning_80, :warning_90)
+      # @yield [ContextManagement::Context] Context with message manipulation methods
+      # @return [void]
+      #
+      # @raise [ArgumentError] If event is unknown or block is missing
+      #
+      # @example Compress tool results at 60%
+      #   on :warning_60 do |ctx|
+      #     ctx.compress_tool_results(keep_recent: 10)
+      #   end
+      #
+      # @example Custom logic at 80%
+      #   on :warning_80 do |ctx|
+      #     if ctx.usage_percentage > 85
+      #       ctx.prune_old_messages(keep_recent: 10)
+      #     else
+      #       ctx.summarize_old_exchanges(older_than: 20)
+      #     end
+      #   end
+      #
+      # @example Log and prune at 90%
+      #   on :warning_90 do |ctx|
+      #     ctx.log_action("critical_threshold", remaining: ctx.tokens_remaining)
+      #     ctx.prune_old_messages(keep_recent: 10)
+      #   end
+      def on(event, &block)
+        threshold = EVENT_MAP[event]
+        raise ArgumentError, "Unknown event: #{event}. Valid events: #{EVENT_MAP.keys.join(", ")}" unless threshold
+        raise ArgumentError, "Block required for #{event}" unless block
+
+        @handlers[threshold] = block
+      end
+
+      # Build hook definitions from handlers
+      #
+      # Creates Hooks::Definition objects that wrap user blocks to provide
+      # rich context objects instead of raw Hooks::Context. Each handler
+      # becomes a hook for the :context_warning event.
+      #
+      # @return [Array<Hooks::Definition>] Hook definitions for :context_warning event
+      def build
+        @handlers.map do |threshold, user_block|
+          # Create a hook that filters by threshold and wraps context
+          Hooks::Definition.new(
+            event: :context_warning,
+            matcher: nil, # No tool matching needed
+            priority: 0,
+            proc: create_threshold_matcher(threshold, user_block),
+          )
+        end
+      end
+
+      private
+
+      # Create a proc that matches threshold and wraps context
+      #
+      # @param target_threshold [Integer] Threshold to match (60, 80, 90)
+      # @param user_block [Proc] User's handler block
+      # @return [Proc] Hook proc
+      def create_threshold_matcher(target_threshold, user_block)
+        proc do |hooks_context|
+          # Only execute for matching threshold
+          current_threshold = hooks_context.metadata[:threshold]
+          next unless current_threshold == target_threshold
+
+          # Wrap in rich context object
+          rich_context = Context.new(hooks_context)
+          user_block.call(rich_context)
+        end
+      end
+    end
+  end
+end

data/lib/swarm_sdk/context_management/context.rb

@@ -0,0 +1,328 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module ContextManagement
+    # Rich context wrapper for context management handlers
+    #
+    # Provides a clean, developer-friendly API for manipulating the conversation
+    # context when warning thresholds are triggered. Wraps the lower-level
+    # Hooks::Context with message manipulation helpers.
+    #
+    # @example Basic usage in handler
+    #   on :warning_60 do |ctx|
+    #     ctx.compress_tool_results(keep_recent: 10)
+    #   end
+    #
+    # @example Advanced usage with metrics
+    #   on :warning_80 do |ctx|
+    #     if ctx.usage_percentage > 85
+    #       ctx.prune_old_messages(keep_recent: 10)
+    #       ctx.log_action("aggressive_pruning", remaining: ctx.tokens_remaining)
+    #     else
+    #       ctx.compress_tool_results(keep_recent: 5, truncate_to: 100)
+    #     end
+    #   end
+    class Context
+      # Create a new context wrapper
+      #
+      # @param hooks_context [Hooks::Context] Lower-level hook context with metadata
+      def initialize(hooks_context)
+        @hooks_context = hooks_context
+        @chat = hooks_context.metadata[:chat]
+      end
+
+      # --- Context Metrics ---
+
+      # Current context usage percentage
+      #
+      # @return [Float] Usage percentage (0.0 to 100.0)
+      #
+      # @example
+      #   if ctx.usage_percentage > 85
+      #     ctx.prune_old_messages(keep_recent: 10)
+      #   end
+      def usage_percentage
+        @hooks_context.metadata[:percentage]
+      end
+
+      # Threshold that triggered this handler
+      #
+      # @return [Integer] Threshold (60, 80, or 90)
+      #
+      # @example
+      #   ctx.log_action("threshold_hit", threshold: ctx.threshold)
+      def threshold
+        @hooks_context.metadata[:threshold]
+      end
+
+      # Total tokens used so far
+      #
+      # @return [Integer] Token count
+      #
+      # @example
+      #   ctx.log_action("usage", tokens: ctx.tokens_used)
+      def tokens_used
+        @hooks_context.metadata[:tokens_used]
+      end
+
+      # Tokens remaining in context window
+      #
+      # @return [Integer] Token count
+      #
+      # @example
+      #   if ctx.tokens_remaining < 10000
+      #     ctx.prune_old_messages(keep_recent: 5)
+      #   end
+      def tokens_remaining
+        @hooks_context.metadata[:tokens_remaining]
+      end
+
+      # Total context window size
+      #
+      # @return [Integer] Token count
+      #
+      # @example
+      #   buffer = ctx.context_limit * 0.1  # 10% buffer
+      def context_limit
+        @hooks_context.metadata[:context_limit]
+      end
+
+      # Agent name
+      #
+      # @return [Symbol] Agent identifier
+      #
+      # @example
+      #   ctx.log_action("agent_context", agent: ctx.agent_name)
+      def agent_name
+        @hooks_context.agent_name
+      end
+
+      # --- Message Access ---
+
+      # Get all messages (copy for manipulation)
+      #
+      # @return [Array<RubyLLM::Message>] Message array
+      #
+      # @example
+      #   ctx.messages.each do |msg|
+      #     puts "#{msg.role}: #{msg.content.length} chars"
+      #   end
+      def messages
+        @chat.messages
+      end
+
+      # Number of messages
+      #
+      # @return [Integer] Message count
+      #
+      # @example
+      #   if ctx.message_count > 100
+      #     ctx.prune_old_messages(keep_recent: 50)
+      #   end
+      def message_count
+        @chat.message_count
+      end
+
+      # --- Message Manipulation ---
+
+      # Replace all messages with new array
+      #
+      # @param new_messages [Array<RubyLLM::Message>] New message array
+      # @return [void]
+      #
+      # @example
+      #   new_msgs = ctx.messages.reject { |m| m.role == :tool }
+      #   ctx.replace_messages(new_msgs)
+      def replace_messages(new_messages)
+        @chat.replace_messages(new_messages)
+      end
+
+      # Compress tool result messages to save context space
+      #
+      # Creates NEW message objects with truncated content (follows RubyLLM patterns).
+      # Truncates old tool results while keeping recent ones intact.
+      # Automatically marks compression as applied to prevent double compression.
+      #
+      # @param keep_recent [Integer] Number of recent tool results to preserve (default: 10)
+      # @param truncate_to [Integer] Max characters for truncated results (default: 200)
+      # @return [Integer] Number of messages compressed
+      #
+      # @example Light compression at 60%
+      #   ctx.compress_tool_results(keep_recent: 15, truncate_to: 500)
+      #
+      # @example Aggressive compression at 80%
+      #   ctx.compress_tool_results(keep_recent: 5, truncate_to: 100)
+      def compress_tool_results(keep_recent: 10, truncate_to: 200)
+        msgs = messages.dup
+        compressed_count = 0
+
+        # Find tool result messages (skip recent ones)
+        tool_indices = []
+        msgs.each_with_index do |msg, idx|
+          tool_indices << idx if msg.role == :tool
+        end
+
+        # Keep recent tool results, compress older ones
+        indices_to_compress = tool_indices[0...-keep_recent] || []
+
+        indices_to_compress.each do |idx|
+          msg = msgs[idx]
+          content = msg.content.to_s
+          next if content.length <= truncate_to
+
+          # Create NEW message with truncated content (NO instance_variable_set!)
+          truncated_content = "#{content[0...truncate_to]}... [truncated for context management]"
+
+          # Create new message object following RubyLLM patterns
+          msgs[idx] = RubyLLM::Message.new(
+            role: :tool,
+            content: truncated_content,
+            tool_call_id: msg.tool_call_id,
+          )
+          compressed_count += 1
+        end
+
+        replace_messages(msgs)
+
+        # Mark compression as applied to coordinate with ContextManager
+        mark_compression_applied
+
+        compressed_count
+      end
+
+      # Mark compression as applied in ContextManager
+      #
+      # Call this when your handler performs compression to prevent
+      # double compression from auto-compression logic.
+      #
+      # @return [void]
+      #
+      # @example Custom compression
+      #   msgs = ctx.messages.map { |m| ... } # custom logic
+      #   ctx.replace_messages(msgs)
+      #   ctx.mark_compression_applied
+      def mark_compression_applied
+        return unless @chat.respond_to?(:context_manager)
+
+        @chat.context_manager.compression_applied = true
+      end
+
+      # Check if compression has already been applied
+      #
+      # @return [Boolean] True if compression was already applied
+      #
+      # @example Conditional compression
+      #   unless ctx.compression_applied?
+      #     ctx.compress_tool_results(keep_recent: 10)
+      #   end
+      def compression_applied?
+        return false unless @chat.respond_to?(:context_manager)
+
+        !!@chat.context_manager.compression_applied
+      end
+
+      # Remove old messages from history
+      #
+      # Keeps system message (if any) and recent exchanges.
+      # This is more aggressive than compression and loses context.
+      #
+      # @param keep_recent [Integer] Number of recent messages to keep (default: 20)
+      # @return [Integer] Number of messages removed
+      #
+      # @example Prune at 80% threshold
+      #   ctx.prune_old_messages(keep_recent: 30)
+      #
+      # @example Emergency pruning at 90%
+      #   ctx.prune_old_messages(keep_recent: 10)
+      def prune_old_messages(keep_recent: 20)
+        msgs = messages.dup
+        original_count = msgs.size
+
+        # Always keep system message if present
+        system_msg = msgs.first if msgs.first&.role == :system
+        non_system = system_msg ? msgs[1..] : msgs
+
+        # Keep only recent messages
+        if non_system.size > keep_recent
+          kept = non_system.last(keep_recent)
+          new_msgs = system_msg ? [system_msg] + kept : kept
+          replace_messages(new_msgs)
+          original_count - new_msgs.size
+        else
+          0
+        end
+      end
+
+      # Summarize old message exchanges
+      #
+      # Groups old user/assistant pairs and replaces with summary.
+      # This is a placeholder - actual implementation would use LLM.
+      #
+      # @param older_than [Integer] Messages older than this index get summarized
+      # @return [Integer] Number of exchanges summarized
+      #
+      # @example
+      #   ctx.summarize_old_exchanges(older_than: 10)
+      def summarize_old_exchanges(older_than: 10)
+        # For now, this is a marker - full implementation would call LLM
+        # to summarize exchanges. We provide the API for developers to
+        # implement their own summarization logic.
+        0
+      end
+
+      # Custom message transformation
+      #
+      # Apply a block to transform messages. This gives full control
+      # over message manipulation for custom strategies.
+      #
+      # @yield [Array<RubyLLM::Message>] Current messages
+      # @yieldreturn [Array<RubyLLM::Message>] Transformed messages
+      # @return [void]
+      #
+      # @example Remove specific tool results
+      #   ctx.transform_messages do |msgs|
+      #     msgs.reject { |m| m.role == :tool && m.content.include?("verbose output") }
+      #   end
+      #
+      # @example Custom compression logic
+      #   ctx.transform_messages do |msgs|
+      #     msgs.map do |m|
+      #       if m.role == :tool && m.content.length > 1000
+      #         RubyLLM::Message.new(role: :tool, content: m.content[0..500], tool_call_id: m.tool_call_id)
+      #       else
+      #         m
+      #       end
+      #     end
+      #   end
+      def transform_messages
+        new_msgs = yield(messages.dup)
+        replace_messages(new_msgs)
+      end
+
+      # Log a context management action
+      #
+      # Emits a log event for tracking what actions were taken.
+      # Useful for debugging and monitoring context management strategies.
+      #
+      # @param action [String] Description of action taken
+      # @param details [Hash] Additional details
+      # @return [void]
+      #
+      # @example Log compression action
+      #   ctx.log_action("compressed_tool_results", count: 5)
+      #
+      # @example Log emergency action
+      #   ctx.log_action("emergency_pruning", remaining: ctx.tokens_remaining)
+      def log_action(action, details = {})
+        LogStream.emit(
+          type: "context_management_action",
+          agent: agent_name,
+          threshold: threshold,
+          action: action,
+          usage_percentage: usage_percentage,
+          **details,
+        )
+      end
+    end
+  end
+end

data/lib/swarm_sdk/defaults.rb

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  # Centralized configuration defaults for SwarmSDK
+  #
+  # This module provides well-documented default values for all configurable
+  # aspects of the SDK. Values are organized by category and include explanations
+  # for their purpose and rationale.
+  #
+  # @example Accessing defaults
+  #   SwarmSDK::Defaults::Timeouts::AGENT_REQUEST_SECONDS
+  #   SwarmSDK::Defaults::Concurrency::GLOBAL_LIMIT
+  #   SwarmSDK::Defaults::Limits::OUTPUT_CHARACTERS
+  module Defaults
+    # Concurrency limits for parallel execution
+    #
+    # These limits prevent overwhelming external services and ensure
+    # fair resource usage across the system.
+    module Concurrency
+      # Maximum concurrent API calls across entire swarm
+      #
+      # This limits total parallel LLM API requests to prevent rate limiting
+      # and excessive resource consumption. 50 is a balanced value that allows
+      # good parallelism while respecting API rate limits.
+      GLOBAL_LIMIT = 50
+
+      # Maximum parallel tool executions per agent
+      #
+      # Limits concurrent tool calls within a single agent. 10 allows
+      # meaningful parallelism (e.g., reading multiple files) without
+      # overwhelming the system.
+      LOCAL_LIMIT = 10
+    end
+
+    # Timeout values for various operations
+    #
+    # All timeouts are in seconds unless explicitly marked as milliseconds.
+    # Timeouts balance responsiveness with allowing enough time for operations
+    # to complete successfully.
+    module Timeouts
+      # LLM API request timeout (seconds)
+      #
+      # Default timeout for Claude/GPT API calls. 5 minutes accommodates
+      # reasoning models (o1, Claude with extended thinking) which can take
+      # longer to process complex queries.
+      AGENT_REQUEST_SECONDS = 300
+
+      # Bash command execution timeout (milliseconds)
+      #
+      # Default timeout for shell commands. 2 minutes balances allowing
+      # build/test commands while preventing runaway processes.
+      BASH_COMMAND_MS = 120_000
+
+      # Maximum Bash command timeout (milliseconds)
+      #
+      # Hard upper limit for bash commands. 10 minutes prevents indefinitely
+      # running commands while allowing long builds/tests.
+      BASH_COMMAND_MAX_MS = 600_000
+
+      # Web fetch timeout (seconds)
+      #
+      # Timeout for HTTP requests in WebFetch tool. 30 seconds is standard
+      # for web requests, allowing slow servers while timing out unresponsive ones.
+      WEB_FETCH_SECONDS = 30
+
+      # Shell hook executor timeout (seconds)
+      #
+      # Default timeout for hook shell commands. 60 seconds allows complex
+      # pre/post hooks while preventing indefinite blocking.
+      HOOK_SHELL_SECONDS = 60
+
+      # Workflow transformer command timeout (seconds)
+      #
+      # Timeout for input/output transformer bash commands. 60 seconds allows
+      # data transformation operations while preventing stalls.
+      TRANSFORMER_COMMAND_SECONDS = 60
+
+      # OpenAI responses API ID TTL (seconds)
+      #
+      # Time-to-live for cached response IDs. 5 minutes allows conversation
+      # continuity while preventing stale cache issues.
+      RESPONSES_API_TTL_SECONDS = 300
+    end
+
+    # Output and content size limits
+    #
+    # These limits prevent overwhelming context windows and ensure
+    # reasonable memory usage.
+    module Limits
+      # Maximum Bash output characters
+      #
+      # Truncates command output to prevent overwhelming agent context.
+      # 30,000 characters balances useful information with context constraints.
+      OUTPUT_CHARACTERS = 30_000
+
+      # Default lines to read from files
+      #
+      # When no explicit limit is set, Read tool returns first 2000 lines.
+      # This provides substantial file content while preventing huge files
+      # from overwhelming context.
+      READ_LINES = 2000
+
+      # Maximum characters per line in Read output
+      #
+      # Truncates very long lines to prevent single lines from consuming
+      # excessive context. 2000 characters per line is generous while
+      # protecting against minified files.
+      LINE_CHARACTERS = 2000
+
+      # Maximum WebFetch content length
+      #
+      # Limits web content fetched from URLs. 100,000 characters provides
+      # substantial page content while preventing huge pages from overwhelming context.
+      WEB_FETCH_CHARACTERS = 100_000
+
+      # Maximum Glob search results
+      #
+      # Limits number of file paths returned by Glob tool. 1000 results
+      # provides comprehensive search while preventing overwhelming output.
+      GLOB_RESULTS = 1000
+    end
+
+    # Storage limits for persistent data
+    module Storage
+      # Maximum size for single scratchpad entry (bytes)
+      #
+      # 3MB per entry prevents individual entries from consuming excessive storage
+      # while allowing substantial content (code, large texts).
+      ENTRY_SIZE_BYTES = 3_000_000
+
+      # Maximum total scratchpad storage (bytes)
+      #
+      # 100GB total storage provides ample room for extensive projects
+      # while preventing unbounded growth.
+      TOTAL_SIZE_BYTES = 100_000_000_000
+    end
+
+    # Context management settings
+    module Context
+      # Context usage percentage triggering compression warning
+      #
+      # When context usage reaches 60%, agents should consider compaction.
+      # This threshold provides buffer before hitting limits.
+      COMPRESSION_THRESHOLD_PERCENT = 60
+
+      # Message count between TodoWrite reminders
+      #
+      # After 8 messages without using TodoWrite, a gentle reminder is injected.
+      # Balances helpfulness without being annoying.
+      TODOWRITE_REMINDER_INTERVAL = 8
+    end
+
+    # Token estimation factors
+    #
+    # Used for approximate token counting when precise counts aren't available.
+    module TokenEstimation
+      # Characters per token for prose text
+      #
+      # Average of ~4 characters per token for natural language text.
+      # Based on empirical analysis of tokenization patterns.
+      CHARS_PER_TOKEN_PROSE = 4.0
+
+      # Characters per token for code
+      #
+      # Code tends to have shorter tokens due to symbols and operators.
+      # ~3.5 characters per token accounts for this density.
+      CHARS_PER_TOKEN_CODE = 3.5
+    end
+
+    # Logging configuration
+    module Logging
+      # Default MCP client log level
+      #
+      # WARN level suppresses verbose MCP client logs while still
+      # reporting important issues.
+      MCP_LOG_LEVEL = Logger::WARN
+    end
+
+    # Agent configuration defaults
+    #
+    # Default values for agent configuration when not explicitly specified.
+    module Agent
+      # Default LLM model identifier
+      #
+      # OpenAI's GPT-5 is used as the default model. This can be overridden
+      # per-agent or globally via all_agents configuration.
+      MODEL = "gpt-5"
+
+      # Default LLM provider
+      #
+      # OpenAI is the default provider. Supported providers include:
+      # openai, anthropic, gemini, deepseek, openrouter, bedrock, etc.
+      PROVIDER = "openai"
+    end
+  end
+end