swarm_sdk 2.0.0.pre.2 → 2.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dfc7f8797b72503c6f69cf0a524bf278c503f59379ff063ad720d34eac2e0244
-  data.tar.gz: b8add20a799625d7c4a067b43eb98bfac926a0ecc56e33c3c5ad0ee02243552b
+  metadata.gz: c45fe12dc7f0cc16c5e82d539f941d22cfc847919f108000b73a6ff259819d24
+  data.tar.gz: cd18d30692c2686c60c3e20e48081ecab97ab81f7bc9051da8bb9a3bf862a979
 SHA512:
-  metadata.gz: 5bf6007ca02a43c843f1f15486a7a5fdca8e269aed37d5ae102c1ee99ce055bb6a4dc34a427da72ce0c8fe84f7e8782b4d4d3ad8ed8010e64741fbfeb5ac0269
-  data.tar.gz: b89b9cef461bd4546f498b6f0f693cc56c4c8c006b6f2e864df4743e3af18aeaf7976ce440c364c031c2764d1ccdae65b7b38d32b5801739ba1a6346e7773a45
+  metadata.gz: 9c1d02a1552463ab920c2e851a47449e6ed6eec82cd8874781cbc37e526937094a0d4b4625ae68596abb1825224fd7021c918f68f32f9d5d900406bf381c883e
+  data.tar.gz: 85ba1af56c5fa6726565a8b65a43a5268aa01ee9381e1c12afc0d0ae75544f82a689bf2939b4b0a9213046c3e8efda84fa83c30a2f06f5bcbc4cd3c1b43fbbeb

data/lib/swarm_sdk/agent/builder.rb

@@ -46,50 +46,66 @@ module SwarmSDK
         @mcp_servers = []
         @include_default_tools = true
         @bypass_permissions = false
-        @skip_base_prompt = false
+        @coding_agent = nil # nil = not set (will default to false in Definition)
         @assume_model_exists = nil
         @hooks = []
         @permissions_config = {}
         @default_permissions = {} # Set by SwarmBuilder from all_agents
       end
 
-      # Set agent model
-      def model(model_name)
+      # Set/get agent model
+      def model(model_name = :__not_provided__)
+        return @model if model_name == :__not_provided__
+
         @model = model_name
       end
 
-      # Set provider
-      def provider(provider_name)
+      # Set/get provider
+      def provider(provider_name = :__not_provided__)
+        return @provider if provider_name == :__not_provided__
+
         @provider = provider_name
       end
 
-      # Set base URL
-      def base_url(url)
+      # Set/get base URL
+      def base_url(url = :__not_provided__)
+        return @base_url if url == :__not_provided__
+
         @base_url = url
       end
 
-      # Set API version (OpenAI-compatible providers only)
-      def api_version(version)
+      # Set/get API version (OpenAI-compatible providers only)
+      def api_version(version = :__not_provided__)
+        return @api_version if version == :__not_provided__
+
         @api_version = version
       end
 
-      # Set explicit context window override
-      def context_window(tokens)
+      # Set/get explicit context window override
+      def context_window(tokens = :__not_provided__)
+        return @context_window if tokens == :__not_provided__
+
         @context_window = tokens
       end
 
-      # Set LLM parameters
-      def parameters(params)
+      # Set/get LLM parameters
+      def parameters(params = :__not_provided__)
+        return @parameters if params == :__not_provided__
+
         @parameters = params
       end
 
-      # Set custom HTTP headers
-      def headers(header_hash)
+      # Set/get custom HTTP headers
+      def headers(header_hash = :__not_provided__)
+        return @headers if header_hash == :__not_provided__
+
         @headers = header_hash
       end
 
-      # Set timeout
-      def timeout(seconds)
+      # Set/get timeout
+      def timeout(seconds = :__not_provided__)
+        return @timeout if seconds == :__not_provided__
+
         @timeout = seconds
       end
 
@@ -118,9 +134,18 @@ module SwarmSDK
         @bypass_permissions = enabled
       end
 
-      # Set skip_base_prompt flag
-      def skip_base_prompt(enabled)
-        @skip_base_prompt = enabled
+      # Set coding_agent flag
+      #
+      # When true, includes the base system prompt for coding tasks.
+      # When false (default), uses only the custom system prompt.
+      #
+      # @param enabled [Boolean] Whether to include base coding prompt
+      # @return [void]
+      #
+      # @example
+      #   coding_agent true  # Include base prompt for coding tasks
+      def coding_agent(enabled)
+        @coding_agent = enabled
       end
 
       # Set assume_model_exists flag
@@ -212,6 +237,78 @@ module SwarmSDK
         @permissions_config = PermissionsBuilder.build(&block)
       end
 
+      # Check if model has been explicitly set (not default)
+      #
+      # Used by Swarm::Builder to determine if all_agents model should apply.
+      #
+      # @return [Boolean] true if model was explicitly set
+      def model_set?
+        @model != "gpt-5"
+      end
+
+      # Check if provider has been explicitly set
+      #
+      # Used by Swarm::Builder to determine if all_agents provider should apply.
+      #
+      # @return [Boolean] true if provider was explicitly set
+      def provider_set?
+        !@provider.nil?
+      end
+
+      # Check if base_url has been explicitly set
+      #
+      # Used by Swarm::Builder to determine if all_agents base_url should apply.
+      #
+      # @return [Boolean] true if base_url was explicitly set
+      def base_url_set?
+        !@base_url.nil?
+      end
+
+      # Check if api_version has been explicitly set
+      #
+      # Used by Swarm::Builder to determine if all_agents api_version should apply.
+      #
+      # @return [Boolean] true if api_version was explicitly set
+      def api_version_set?
+        !@api_version.nil?
+      end
+
+      # Check if timeout has been explicitly set
+      #
+      # Used by Swarm::Builder to determine if all_agents timeout should apply.
+      #
+      # @return [Boolean] true if timeout was explicitly set
+      def timeout_set?
+        !@timeout.nil?
+      end
+
+      # Check if coding_agent has been explicitly set
+      #
+      # Used by Swarm::Builder to determine if all_agents coding_agent should apply.
+      #
+      # @return [Boolean] true if coding_agent was explicitly set
+      def coding_agent_set?
+        !@coding_agent.nil?
+      end
+
+      # Check if parameters have been set
+      #
+      # Used by Swarm::Builder for merging all_agents parameters.
+      #
+      # @return [Boolean] true if parameters were set
+      def parameters_set?
+        @parameters.any?
+      end
+
+      # Check if headers have been set
+      #
+      # Used by Swarm::Builder for merging all_agents headers.
+      #
+      # @return [Boolean] true if headers were set
+      def headers_set?
+        @headers.any?
+      end
+
       # Build and return an Agent::Definition
       #
       # This method converts the builder's configuration into a validated
@@ -242,7 +339,7 @@ module SwarmSDK
         agent_config[:mcp_servers] = @mcp_servers if @mcp_servers.any?
         agent_config[:include_default_tools] = @include_default_tools
         agent_config[:bypass_permissions] = @bypass_permissions
-        agent_config[:skip_base_prompt] = @skip_base_prompt
+        agent_config[:coding_agent] = @coding_agent
         agent_config[:assume_model_exists] = @assume_model_exists unless @assume_model_exists.nil?
         agent_config[:permissions] = @permissions_config if @permissions_config.any?
         agent_config[:default_permissions] = @default_permissions if @default_permissions.any?

data/lib/swarm_sdk/agent/definition.rb

@@ -39,7 +39,7 @@ module SwarmSDK
         :headers,
         :timeout,
         :include_default_tools,
-        :skip_base_prompt,
+        :coding_agent,
         :default_permissions,
         :agent_permissions,
         :assume_model_exists,
@@ -83,8 +83,10 @@ module SwarmSDK
         # include_default_tools defaults to true if not specified
         @include_default_tools = config.key?(:include_default_tools) ? config[:include_default_tools] : true
 
-        # skip_base_prompt defaults to false if not specified
-        @skip_base_prompt = config.key?(:skip_base_prompt) ? config[:skip_base_prompt] : false
+        # coding_agent defaults to false if not specified
+        # When true, includes the base system prompt for coding tasks
+        # When false, uses only the custom system prompt (no base prompt)
+        @coding_agent = config.key?(:coding_agent) ? config[:coding_agent] : false
 
         # Parse directory first so it can be used in system prompt rendering
         @directory = parse_directory(config[:directory])
@@ -132,26 +134,107 @@ module SwarmSDK
           timeout: @timeout,
           bypass_permissions: @bypass_permissions,
           include_default_tools: @include_default_tools,
-          skip_base_prompt: @skip_base_prompt,
+          coding_agent: @coding_agent,
           assume_model_exists: @assume_model_exists,
           max_concurrent_tools: @max_concurrent_tools,
           hooks: @hooks,
         }.compact
       end
 
+      # Validate agent configuration and return warnings (non-fatal issues)
+      #
+      # Unlike validate! which raises exceptions for critical errors, this method
+      # returns an array of warning hashes for non-fatal issues like:
+      # - Model not found in registry (informs user, suggests alternatives)
+      # - Context tracking unavailable (useful even with assume_model_exists)
+      #
+      # Note: Validation ALWAYS runs, even with assume_model_exists: true or base_url set.
+      # The purpose is to inform the user about potential issues and suggest corrections,
+      # not to block execution.
+      #
+      # @return [Array<Hash>] Array of warning hashes
+      def validate
+        warnings = []
+
+        # Always validate model (even with assume_model_exists)
+        # Warnings inform user about typos and context tracking limitations
+        model_warning = validate_model
+        warnings << model_warning if model_warning
+
+        # Future: could add tool validation, delegate validation, etc.
+
+        warnings
+      end
+
       private
 
-      def build_full_system_prompt(custom_prompt)
-        # If skip_base_prompt is true, return only the custom prompt (or empty string if nil)
-        if @skip_base_prompt
-          return (custom_prompt || "").to_s
-        end
+      # Validate that model exists in RubyLLM registry
+      #
+      # @return [Hash, nil] Warning hash if model not found, nil otherwise
+      def validate_model
+        # Try to find model in registry (searches all providers)
+        RubyLLM.models.find(@model)
+        nil # Model exists
+      rescue StandardError => e
+        # Model not found - return warning with suggestions
+        {
+          type: :model_not_found,
+          agent: @name,
+          model: @model,
+          error_message: e.message,
+          suggestions: suggest_similar_models,
+        }
+      end
 
-        rendered_base = render_base_system_prompt
+      # Suggest similar models when a model is not found
+      #
+      # @return [Array<Hash>] Up to 3 similar models with their info
+      def suggest_similar_models
+        normalized_query = @model.to_s.downcase.gsub(/[.\-_]/, "")
+
+        RubyLLM.models.all.select do |model_info|
+          normalized_id = model_info.id.downcase.gsub(/[.\-_]/, "")
+          normalized_id.include?(normalized_query) ||
+            model_info.name&.downcase&.gsub(/[.\-_]/, "")&.include?(normalized_query)
+        end.first(3).map do |model_info|
+          {
+            id: model_info.id,
+            name: model_info.name,
+            context_window: model_info.context_window,
+          }
+        end
+      rescue StandardError
+        []
+      end
 
-        return rendered_base if custom_prompt.nil? || custom_prompt.strip.empty?
+      def build_full_system_prompt(custom_prompt)
+        # If coding_agent is false (default), return custom prompt with optional TODO/Scratchpad info
+        # If coding_agent is true, include full base prompt for coding tasks
+        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 @include_default_tools
+          # Non-coding agent: optionally include TODO/Scratchpad sections if default tools available
+          non_coding_base = render_non_coding_base_prompt
 
-        "#{rendered_base}\n\n#{custom_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
+        # Default tools available: include TODO/Scratchpad instructions
+        else
+          # No default tools: return only custom prompt
+          (custom_prompt || "").to_s
+        end
       end
 
       def render_base_system_prompt
@@ -168,6 +251,32 @@ module SwarmSDK
         ERB.new(template_content).result(binding)
       end
 
+      def render_non_coding_base_prompt
+        # Simplified base prompt for non-coding agents
+        # Only includes TODO and Scratchpad tool information
+        # Does not steer towards coding tasks
+        <<~PROMPT.strip
+          # 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)

data/lib/swarm_sdk/configuration.rb

@@ -147,16 +147,31 @@ module SwarmSDK
       swarm_agents = @config[:swarm][:agents]
 
       swarm_agents.each do |name, agent_config|
-        agent_config ||= {}
-
-        # Merge all_agents_config into agent config
-        # Agent-specific config overrides all_agents config
-        merged_config = merge_all_agents_config(agent_config)
-
-        @agents[name] = if agent_config[:agent_file]
-          load_agent_from_file(name, agent_config[:agent_file], merged_config)
+        # Support three formats:
+        # 1. String: assistant: "agents/assistant.md" (file path)
+        # 2. Hash with agent_file: assistant: { agent_file: "..." }
+        # 3. Hash with inline definition: assistant: { description: "...", model: "..." }
+
+        if agent_config.is_a?(String)
+          # Format 1: Direct file path as string
+          file_path = agent_config
+          merged_config = merge_all_agents_config({})
+          @agents[name] = load_agent_from_file(name, file_path, merged_config)
         else
-          Agent::Definition.new(name, merged_config)
+          # Format 2 or 3: Hash configuration
+          agent_config ||= {}
+
+          # Merge all_agents_config into agent config
+          # Agent-specific config overrides all_agents config
+          merged_config = merge_all_agents_config(agent_config)
+
+          @agents[name] = if agent_config[:agent_file]
+            # Format 2: Hash with agent_file key
+            load_agent_from_file(name, agent_config[:agent_file], merged_config)
+          else
+            # Format 3: Inline definition
+            Agent::Definition.new(name, merged_config)
+          end
         end
       end
 
@@ -167,10 +182,19 @@ module SwarmSDK
 
     # Merge all_agents config with agent-specific config
     # Agent config takes precedence over all_agents config
+    #
+    # Merge strategy:
+    # - Arrays (tools, delegates_to): Concatenate
+    # - Hashes (parameters, headers): Merge (agent values override)
+    # - Scalars (model, provider, base_url, timeout, coding_agent): Agent overrides
+    #
+    # @param agent_config [Hash] Agent-specific configuration
+    # @return [Hash] Merged configuration
     def merge_all_agents_config(agent_config)
       merged = @all_agents_config.dup
 
-      # For arrays (like tools, delegates_to), concatenate instead of replace
+      # For arrays, concatenate
+      # For hashes, merge (agent values override)
       # For scalars, agent value overrides
       agent_config.each do |key, value|
         case key
@@ -180,8 +204,17 @@ module SwarmSDK
         when :delegates_to
           # Concatenate delegates_to
           merged[:delegates_to] = Array(merged[:delegates_to]) + Array(value)
+        when :parameters
+          # Merge parameters: all_agents.parameters + agent.parameters
+          # Agent values override all_agents values for same keys
+          merged[:parameters] = (merged[:parameters] || {}).merge(value || {})
+        when :headers
+          # Merge headers: all_agents.headers + agent.headers
+          # Agent values override all_agents values for same keys
+          merged[:headers] = (merged[:headers] || {}).merge(value || {})
         else
-          # For everything else, agent value overrides all_agents value
+          # For everything else (model, provider, base_url, timeout, coding_agent, etc.),
+          # agent value overrides all_agents value
           merged[key] = value
         end
       end

data/lib/swarm_sdk/hooks/context.rb

@@ -158,6 +158,40 @@ module SwarmSDK
       def finish_swarm(message)
         Result.finish_swarm(message)
       end
+
+      # Enter an interactive debugging breakpoint
+      #
+      # This method:
+      # 1. Emits a breakpoint_enter event (formatters can pause spinners)
+      # 2. Opens binding.irb for interactive debugging
+      # 3. Emits a breakpoint_exit event (formatters can resume spinners)
+      #
+      # @example Use in a hook
+      #   hook(:pre_delegation) do |ctx|
+      #     ctx.breakpoint  # Pause execution and inspect context
+      #   end
+      #
+      # @return [void]
+      def breakpoint
+        # Emit breakpoint_enter event
+        LogStream.emit(
+          type: "breakpoint_enter",
+          agent: @agent_name,
+          event: @event,
+          timestamp: Time.now.utc.iso8601,
+        )
+
+        # Enter interactive debugging
+        binding.irb # rubocop:disable Lint/Debugger
+
+        # Emit breakpoint_exit event
+        LogStream.emit(
+          type: "breakpoint_exit",
+          agent: @agent_name,
+          event: @event,
+          timestamp: Time.now.utc.iso8601,
+        )
+      end
     end
   end
 end

data/lib/swarm_sdk/hooks/registry.rb

@@ -41,6 +41,10 @@ module SwarmSDK
 
         # Context events
         :context_warning, # When context usage crosses threshold
+
+        # Debug events
+        :breakpoint_enter,  # When entering interactive debugging (binding.irb)
+        :breakpoint_exit,   # When exiting interactive debugging
       ].freeze
 
       def initialize

data/lib/swarm_sdk/log_collector.rb

@@ -14,30 +14,18 @@ module SwarmSDK
   #     puts JSON.generate(event)
   #   end
   #
-  #   # Freeze callbacks (after all registrations, before Async execution)
-  #   LogCollector.freeze!
-  #
   #   # During execution, LogStream calls emit
   #   LogCollector.emit(type: "user_prompt", agent: :backend)
   #
-  # ## Fiber Safety
-  #
-  # LogCollector is fiber-safe because:
-  # - All callbacks registered before Async execution starts
-  # - freeze! makes @callbacks immutable
-  # - emit() only reads the frozen array (no mutations)
+  #   # After execution, reset for next use
+  #   LogCollector.reset!
   #
   module LogCollector
     class << self
       # Register a callback to receive log events
       #
-      # Must be called before freeze! is called.
-      #
       # @yield [Hash] Log event entry
-      # @raise [StateError] If called after freeze!
       def on_log(&block)
-        raise StateError, "Cannot register callbacks after LogCollector is frozen" if @frozen
-
         @callbacks ||= []
         @callbacks << block
       end
@@ -47,36 +35,16 @@ module SwarmSDK
       # @param entry [Hash] Log event entry
       # @return [void]
       def emit(entry)
-        # Use defensive copy for fiber safety
         Array(@callbacks).each do |callback|
           callback.call(entry)
         end
       end
 
-      # Freeze the callbacks array (call before Async execution)
-      #
-      # This prevents new callbacks from being registered and makes
-      # the array immutable for fiber safety.
-      #
-      # @return [void]
-      def freeze!
-        @callbacks&.freeze
-        @frozen = true
-      end
-
-      # Reset the collector (for test cleanup)
+      # Reset the collector (clears callbacks for next execution)
       #
       # @return [void]
       def reset!
         @callbacks = []
-        @frozen = false
-      end
-
-      # Check if collector is frozen
-      #
-      # @return [Boolean]
-      def frozen?
-        @frozen
       end
     end
   end

data/lib/swarm_sdk/node/agent_config.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module Node
+    # AgentConfig provides fluent API for configuring agents within a node
+    #
+    # This class enables the chainable syntax:
+    #   agent(:backend).delegates_to(:tester, :database)
+    #
+    # @example Basic delegation
+    #   agent(:backend).delegates_to(:tester)
+    #
+    # @example No delegation (solo agent)
+    #   agent(:planner)
+    class AgentConfig
+      attr_reader :agent_name
+
+      def initialize(agent_name, node_builder)
+        @agent_name = agent_name
+        @node_builder = node_builder
+        @delegates_to = []
+        @finalized = false
+      end
+
+      # Set delegation targets for this agent
+      #
+      # @param agent_names [Array<Symbol>] Names of agents to delegate to
+      # @return [self] For method chaining
+      def delegates_to(*agent_names)
+        @delegates_to = agent_names.map(&:to_sym)
+        finalize
+        self
+      end
+
+      # Finalize agent configuration (called automatically)
+      #
+      # Registers this agent configuration with the parent node builder.
+      # If delegates_to was never called, registers with empty delegation.
+      #
+      # @return [void]
+      def finalize
+        return if @finalized
+
+        @node_builder.register_agent(@agent_name, @delegates_to)
+        @finalized = true
+      end
+    end
+  end
+end