swarm_sdk 2.7.14 → 3.0.0.alpha1

data/lib/swarm_sdk/defaults.rb

@@ -1,251 +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
-
-      # Execution timeout (seconds)
-      #
-      # Maximum wall-clock time for entire swarm.execute() call.
-      # 30 minutes allows complex multi-agent workflows while preventing
-      # runaway execution.
-      EXECUTION_TIMEOUT_SECONDS = 1800
-
-      # Turn timeout (seconds)
-      #
-      # Maximum time for a single agent.ask() call, including all LLM requests
-      # and tool executions. 30 minutes accommodates extended thinking models
-      # and complex tool chains.
-      TURN_TIMEOUT_SECONDS = 1800
-
-      # 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
-
-      # MCP client request timeout (seconds)
-      #
-      # Default timeout for MCP server connections. 5 minutes accommodates
-      # long-running SSE streams and tool executions. This timeout applies to
-      # the entire operation (operation_timeout in HTTPX), so it must be long
-      # enough for SSE connections that may run for extended periods.
-      MCP_REQUEST_SECONDS = 300
-    end
-
-    # MCP reconnection configuration
-    #
-    # Settings for automatic reconnection when SSE/streamable connections drop.
-    # Note: The background SSE notification stream uses operation_timeout which
-    # limits total connection duration. Since this stream is meant to stay open
-    # indefinitely for server notifications, we configure aggressive reconnection
-    # so timeouts are transparent to users. Tool calls use separate connections
-    # and are unaffected by SSE stream timeouts.
-    module McpReconnection
-      # Maximum number of reconnection attempts
-      #
-      # Very high value (effectively infinite) because the SSE notification stream
-      # is expected to timeout periodically due to operation_timeout limitations.
-      # Reconnection is transparent - tool calls continue working regardless.
-      MAX_RETRIES = 1000
-
-      # Initial delay between reconnection attempts (milliseconds)
-      #
-      # Fast initial reconnect (500ms) to minimize notification gaps.
-      INITIAL_DELAY_MS = 500
-
-      # Exponential backoff growth factor
-      #
-      # Slow growth (1.2x) because we expect frequent reconnections.
-      # 500ms -> 600ms -> 720ms -> 864ms -> 1037ms -> ...
-      DELAY_GROW_FACTOR = 1.2
-
-      # Maximum delay between reconnection attempts (milliseconds)
-      #
-      # Caps at 10 seconds to ensure responsive reconnection even after many retries.
-      MAX_DELAY_MS = 10_000
-    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

data/lib/swarm_sdk/events_to_messages.rb

@@ -1,199 +0,0 @@
-# frozen_string_literal: true
-
-module SwarmSDK
-  # Reconstructs RubyLLM::Message objects from SwarmSDK event streams
-  #
-  # This class enables conversation replay and analysis from event logs.
-  # It uses timestamps to maintain chronological ordering of messages.
-  #
-  # ## Limitations
-  #
-  # This reconstructs ONLY conversation messages. It does NOT restore:
-  # - Context state (warning thresholds, compression, todowrite index)
-  # - Scratchpad contents
-  # - Read tracking information
-  # - Full swarm state
-  #
-  # For full state restoration, use StateSnapshot/StateRestorer or SnapshotFromEvents.
-  #
-  # ## Usage
-  #
-  #   # Collect events during execution
-  #   events = []
-  #   swarm.execute("Build feature") do |event|
-  #     events << event
-  #   end
-  #
-  #   # Reconstruct conversation for an agent
-  #   messages = SwarmSDK::EventsToMessages.reconstruct(events, agent: :backend)
-  #
-  #   # View conversation
-  #   messages.each do |msg|
-  #     puts "[#{msg.role}] #{msg.content}"
-  #   end
-  #
-  # ## Event Requirements
-  #
-  # Events must have:
-  # - `:timestamp` field (ISO 8601 format) for ordering
-  # - `:agent` field to filter by agent
-  # - `:type` field to identify event type
-  #
-  # Supported event types:
-  # - `user_prompt`: Reconstructs user message (prompt in metadata or top-level)
-  # - `agent_step`: Reconstructs assistant message with tool calls
-  # - `agent_stop`: Reconstructs final assistant message
-  # - `tool_result`: Reconstructs tool result message
-  # - `delegation_result`: Reconstructs tool result message from delegation
-  class EventsToMessages
-    class << self
-      # Reconstruct messages for an agent from event stream
-      #
-      # @param events [Array<Hash>] Event stream with timestamps
-      # @param agent [Symbol, String] Agent name to reconstruct messages for
-      # @return [Array<RubyLLM::Message>] Reconstructed messages in chronological order
-      #
-      # @example
-      #   messages = EventsToMessages.reconstruct(events, agent: :backend)
-      #   messages.each { |msg| puts msg.content }
-      def reconstruct(events, agent:)
-        new(events, agent).reconstruct
-      end
-    end
-
-    # Initialize reconstructor
-    #
-    # @param events [Array<Hash>] Event stream
-    # @param agent [Symbol, String] Agent name
-    def initialize(events, agent)
-      @events = events
-      @agent = agent.to_sym
-    end
-
-    # Reconstruct messages from events
-    #
-    # Filters events by agent, sorts by timestamp, and converts to RubyLLM::Message objects.
-    #
-    # @return [Array<RubyLLM::Message>] Reconstructed messages
-    def reconstruct
-      messages = []
-
-      # Filter events for this agent and sort by timestamp
-      agent_events = @events
-        .select { |e| normalize_agent(e[:agent]) == @agent }
-        .sort_by { |e| parse_timestamp(e[:timestamp]) }
-
-      agent_events.each do |event|
-        message = case event[:type]&.to_s
-        when "user_prompt"
-          reconstruct_user_message(event)
-        when "agent_step", "agent_stop"
-          reconstruct_assistant_message(event)
-        when "tool_result"
-          reconstruct_tool_result_message(event)
-        when "delegation_result"
-          reconstruct_delegation_result_message(event)
-        end
-
-        messages << message if message
-      end
-
-      messages
-    end
-
-    private
-
-    # Reconstruct user message from user_prompt event
-    #
-    # Extracts prompt from metadata or top-level field.
-    #
-    # @param event [Hash] user_prompt event
-    # @return [RubyLLM::Message, nil] User message or nil if prompt not found
-    def reconstruct_user_message(event)
-      # Try to extract prompt from metadata (current location) or top-level (potential future location)
-      prompt = event.dig(:metadata, :prompt) || event[:prompt]
-      return unless prompt && !prompt.to_s.empty?
-
-      RubyLLM::Message.new(
-        role: :user,
-        content: prompt,
-      )
-    end
-
-    # Reconstruct assistant message from agent_step or agent_stop event
-    #
-    # Converts tool_calls array to hash format expected by RubyLLM.
-    #
-    # @param event [Hash] agent_step or agent_stop event
-    # @return [RubyLLM::Message] Assistant message
-    def reconstruct_assistant_message(event)
-      # Convert tool_calls array to hash (RubyLLM format)
-      # Events emit tool_calls as Array, but RubyLLM expects Hash<String, ToolCall>
-      tool_calls_hash = if event[:tool_calls] && !event[:tool_calls].empty?
-        event[:tool_calls].each_with_object({}) do |tc, hash|
-          hash[tc[:id].to_s] = RubyLLM::ToolCall.new(
-            id: tc[:id],
-            name: tc[:name],
-            arguments: tc[:arguments] || {},
-          )
-        end
-      end
-
-      RubyLLM::Message.new(
-        role: :assistant,
-        content: event[:content] || "",
-        tool_calls: tool_calls_hash,
-        input_tokens: event.dig(:usage, :input_tokens),
-        output_tokens: event.dig(:usage, :output_tokens),
-        model_id: event[:model],
-      )
-    end
-
-    # Reconstruct tool result message from tool_result event
-    #
-    # @param event [Hash] tool_result event
-    # @return [RubyLLM::Message] Tool result message
-    def reconstruct_tool_result_message(event)
-      RubyLLM::Message.new(
-        role: :tool,
-        content: event[:result].to_s,
-        tool_call_id: event[:tool_call_id],
-      )
-    end
-
-    # Reconstruct tool result message from delegation_result event
-    #
-    # delegation_result events are emitted when a delegation completes,
-    # and they should be converted to tool result messages in the conversation.
-    #
-    # @param event [Hash] delegation_result event
-    # @return [RubyLLM::Message] Tool result message
-    def reconstruct_delegation_result_message(event)
-      RubyLLM::Message.new(
-        role: :tool,
-        content: event[:result].to_s,
-        tool_call_id: event[:tool_call_id],
-      )
-    end
-
-    # Parse timestamp string to Time object
-    #
-    # @param timestamp [String, nil] ISO 8601 timestamp
-    # @return [Time] Parsed time or epoch if nil/invalid
-    def parse_timestamp(timestamp)
-      return Time.at(0) unless timestamp
-
-      Time.parse(timestamp)
-    rescue ArgumentError
-      Time.at(0)
-    end
-
-    # Normalize agent name to symbol
-    #
-    # @param agent [Symbol, String, nil] Agent name
-    # @return [Symbol] Normalized agent name
-    def normalize_agent(agent)
-      agent.to_s.to_sym
-    end
-  end
-end