swarm_memory 2.1.5 → 2.1.6

data/lib/swarm_sdk/context_management/context.rb

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

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