swarm_sdk 2.0.0.pre.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: dfc7f8797b72503c6f69cf0a524bf278c503f59379ff063ad720d34eac2e0244
+  data.tar.gz: b8add20a799625d7c4a067b43eb98bfac926a0ecc56e33c3c5ad0ee02243552b
+SHA512:
+  metadata.gz: 5bf6007ca02a43c843f1f15486a7a5fdca8e269aed37d5ae102c1ee99ce055bb6a4dc34a427da72ce0c8fe84f7e8782b4d4d3ad8ed8010e64741fbfeb5ac0269
+  data.tar.gz: b89b9cef461bd4546f498b6f0f693cc56c4c8c006b6f2e864df4743e3af18aeaf7976ce440c364c031c2764d1ccdae65b7b38d32b5801739ba1a6346e7773a45

data/lib/swarm_sdk/agent/builder.rb

@@ -0,0 +1,333 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module Agent
+    # Builder provides fluent API for configuring agents
+    #
+    # This class offers a Ruby DSL for defining agents with a clean, readable syntax.
+    # It collects configuration and then adds the agent to the swarm.
+    #
+    # @example
+    #   agent :backend do
+    #     model "gpt-5"
+    #     prompt "You build APIs"
+    #     tools :Read, :Write, :Bash
+    #
+    #     hook :pre_tool_use, matcher: "Bash" do |ctx|
+    #       SwarmSDK::Hooks::Result.halt("Blocked!") if dangerous?(ctx)
+    #     end
+    #   end
+    class Builder
+      # Expose default_permissions for Swarm::Builder to set from all_agents
+      attr_writer :default_permissions
+
+      # Expose mcp_servers for tests
+      attr_reader :mcp_servers
+
+      def initialize(name)
+        @name = name
+        @description = nil
+        @model = "gpt-5"
+        @provider = nil
+        @base_url = nil
+        @api_version = nil
+        @context_window = nil
+        @system_prompt = nil
+        # Use Set for tools to automatically handle duplicates when tools() is called multiple times.
+        # This ensures that if someone does: tools :Read; tools :Write; tools :Read
+        # the final set contains only [:Read, :Write] without duplicates.
+        # We convert to Array in to_definition for compatibility with Agent::Definition.
+        @tools = Set.new
+        @delegates_to = []
+        @directory = "."
+        @parameters = {}
+        @headers = {}
+        @timeout = nil
+        @mcp_servers = []
+        @include_default_tools = true
+        @bypass_permissions = false
+        @skip_base_prompt = false
+        @assume_model_exists = nil
+        @hooks = []
+        @permissions_config = {}
+        @default_permissions = {} # Set by SwarmBuilder from all_agents
+      end
+
+      # Set agent model
+      def model(model_name)
+        @model = model_name
+      end
+
+      # Set provider
+      def provider(provider_name)
+        @provider = provider_name
+      end
+
+      # Set base URL
+      def base_url(url)
+        @base_url = url
+      end
+
+      # Set API version (OpenAI-compatible providers only)
+      def api_version(version)
+        @api_version = version
+      end
+
+      # Set explicit context window override
+      def context_window(tokens)
+        @context_window = tokens
+      end
+
+      # Set LLM parameters
+      def parameters(params)
+        @parameters = params
+      end
+
+      # Set custom HTTP headers
+      def headers(header_hash)
+        @headers = header_hash
+      end
+
+      # Set timeout
+      def timeout(seconds)
+        @timeout = seconds
+      end
+
+      # Add an MCP server configuration
+      #
+      # @example stdio transport
+      #   mcp_server :filesystem, type: :stdio, command: "npx", args: ["-y", "@modelcontextprotocol/server-filesystem"]
+      #
+      # @example SSE transport
+      #   mcp_server :web, type: :sse, url: "https://example.com/mcp", headers: { authorization: "Bearer token" }
+      #
+      # @example HTTP/streamable transport
+      #   mcp_server :api, type: :http, url: "https://api.example.com/mcp", timeout: 60
+      def mcp_server(name, **options)
+        server_config = { name: name }.merge(options)
+        @mcp_servers << server_config
+      end
+
+      # Set include_default_tools flag (deprecated - use tools method with include_default parameter)
+      def include_default_tools(enabled)
+        @include_default_tools = enabled
+      end
+
+      # Set bypass_permissions flag
+      def bypass_permissions(enabled)
+        @bypass_permissions = enabled
+      end
+
+      # Set skip_base_prompt flag
+      def skip_base_prompt(enabled)
+        @skip_base_prompt = enabled
+      end
+
+      # Set assume_model_exists flag
+      def assume_model_exists(enabled)
+        @assume_model_exists = enabled
+      end
+
+      # Set system prompt (matches YAML key)
+      def system_prompt(text)
+        @system_prompt = text
+      end
+
+      # Set description
+      def description(text)
+        @description = text
+      end
+
+      # Add tools
+      #
+      # Uses Set internally to automatically deduplicate tool names across multiple calls.
+      # This allows calling tools() multiple times without worrying about duplicates.
+      #
+      # @param tool_names [Array<Symbol>] Tool names to add
+      # @param include_default [Boolean] Whether to include default tools (Read, Grep, etc.)
+      #
+      # @example Basic usage with defaults
+      #   tools :Grep, :Read  # include_default: true is implicit
+      #
+      # @example Explicit tools only, no defaults
+      #   tools :Grep, :Read, include_default: false
+      #
+      # @example Multiple calls (cumulative, automatic deduplication)
+      #   tools :Read
+      #   tools :Write, :Edit  # @tools now contains Set[:Read, :Write, :Edit]
+      #   tools :Read          # Still Set[:Read, :Write, :Edit] - no duplicate
+      def tools(*tool_names, include_default: true)
+        @tools.merge(tool_names.map(&:to_sym))
+        @include_default_tools = include_default
+      end
+
+      # Add tools from all_agents configuration
+      #
+      # Used by Swarm::Builder to add all_agents tools.
+      # Since we use Set, order doesn't matter and duplicates are handled automatically.
+      #
+      # @param tool_names [Array] Tool names to add
+      # @return [void]
+      def prepend_tools(*tool_names)
+        @tools.merge(tool_names.map(&:to_sym))
+      end
+
+      # Set directory
+      def directory(dir)
+        @directory = dir
+      end
+
+      # Set delegation targets
+      def delegates_to(*agent_names)
+        @delegates_to.concat(agent_names)
+      end
+
+      # Add a hook (Ruby block OR shell command)
+      #
+      # @example Ruby block
+      #   hook :pre_tool_use, matcher: "Bash" do |ctx|
+      #     HookResult.halt("Blocked") if dangerous?(ctx)
+      #   end
+      #
+      # @example Shell command
+      #   hook :pre_tool_use, matcher: "Bash", command: "validate.sh"
+      def hook(event, matcher: nil, command: nil, timeout: nil, &block)
+        @hooks << {
+          event: event,
+          matcher: matcher,
+          command: command,
+          timeout: timeout,
+          block: block,
+        }
+      end
+
+      # Configure permissions for this agent
+      #
+      # @example
+      #   permissions do
+      #     Write.allow_paths "backend/**/*"
+      #     Write.deny_paths "backend/secrets/**"
+      #   end
+      def permissions(&block)
+        @permissions_config = PermissionsBuilder.build(&block)
+      end
+
+      # Build and return an Agent::Definition
+      #
+      # This method converts the builder's configuration into a validated
+      # Agent::Definition object. The caller is responsible for adding it to a swarm.
+      #
+      # Converts @tools Set to Array here because Agent::Definition expects an array.
+      # The Set was only used during building to handle duplicates efficiently.
+      #
+      # @return [Agent::Definition] Fully configured and validated agent definition
+      def to_definition
+        agent_config = {
+          description: @description || "Agent #{@name}",
+          model: @model,
+          system_prompt: @system_prompt,
+          tools: @tools.to_a, # Convert Set to Array for Agent::Definition compatibility
+          delegates_to: @delegates_to,
+          directory: @directory,
+        }
+
+        # Add optional fields
+        agent_config[:provider] = @provider if @provider
+        agent_config[:base_url] = @base_url if @base_url
+        agent_config[:api_version] = @api_version if @api_version
+        agent_config[:context_window] = @context_window if @context_window
+        agent_config[:parameters] = @parameters if @parameters.any?
+        agent_config[:headers] = @headers if @headers.any?
+        agent_config[:timeout] = @timeout if @timeout
+        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[: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?
+
+        # Convert DSL hooks to HookDefinition format
+        agent_config[:hooks] = convert_hooks_to_definitions if @hooks.any?
+
+        Agent::Definition.new(@name, agent_config)
+      end
+
+      private
+
+      # Convert DSL hooks to HookDefinition objects for Agent::Definition
+      #
+      # This converts the builder's hook configuration (Ruby blocks and shell commands)
+      # into HookDefinition objects that will be applied during agent initialization.
+      #
+      # @return [Hash] Hooks grouped by event type { event: [HookDefinition, ...] }
+      def convert_hooks_to_definitions
+        result = Hash.new { |h, k| h[k] = [] }
+
+        @hooks.each do |hook_config|
+          event = hook_config[:event]
+
+          # Create HookDefinition with proc or command
+          if hook_config[:block]
+            # Ruby block hook
+            hook_def = Hooks::Definition.new(
+              event: event,
+              matcher: hook_config[:matcher],
+              priority: 0,
+              proc: hook_config[:block],
+            )
+          elsif hook_config[:command]
+            # Shell command hook - wrap in a block that calls ShellExecutor
+            hook_def = Hooks::Definition.new(
+              event: event,
+              matcher: hook_config[:matcher],
+              priority: 0,
+              proc: create_shell_hook_proc(hook_config),
+            )
+          else
+            raise ConfigurationError, "Hook must have either :block or :command"
+          end
+
+          result[event] << hook_def
+        end
+
+        result
+      end
+
+      # Create a proc that executes a shell command hook
+      def create_shell_hook_proc(config)
+        command = config[:command]
+        timeout = config[:timeout] || 60
+        agent_name = @name
+
+        proc do |context|
+          input_json = build_hook_input(context, config[:event])
+          Hooks::ShellExecutor.execute(
+            command: command,
+            input_json: input_json,
+            timeout: timeout,
+            agent_name: agent_name,
+            swarm_name: context.swarm&.name,
+            event: config[:event],
+          )
+        end
+      end
+
+      # Build hook input JSON for shell command hooks
+      def build_hook_input(context, event)
+        base = { event: event.to_s, agent: @name.to_s }
+
+        case event
+        when :pre_tool_use
+          base.merge(tool: context.tool_call.name, parameters: context.tool_call.parameters)
+        when :post_tool_use
+          base.merge(result: context.tool_result.content, success: context.tool_result.success?)
+        when :user_prompt
+          base.merge(prompt: context.metadata[:prompt])
+        else
+          base
+        end
+      end
+    end
+  end
+end

data/lib/swarm_sdk/agent/chat/context_tracker.rb

@@ -0,0 +1,271 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module Agent
+    class Chat < RubyLLM::Chat
+      # Manages context tracking, delegation tracking, and logging callbacks
+      #
+      # Responsibilities:
+      # - Register RubyLLM callbacks for logging
+      # - Track tool executions
+      # - Track delegations (which tool calls are delegations)
+      # - Emit log events via LogStream
+      # - Check context warnings
+      #
+      # This is a stateful helper that's instantiated per Agent::Chat instance.
+      class ContextTracker
+        include LoggingHelpers
+
+        attr_reader :agent_context
+
+        def initialize(chat, agent_context)
+          @chat = chat
+          @agent_context = agent_context
+          @tool_executions = []
+          @finish_reason_override = nil
+        end
+
+        # Set a custom finish reason for the next agent_stop event
+        #
+        # This is used when finish_agent or finish_swarm terminates execution early.
+        #
+        # @param reason [String] Custom finish reason (e.g., "finish_agent", "finish_swarm")
+        attr_writer :finish_reason_override
+
+        # Setup logging callbacks
+        #
+        # Registers RubyLLM callbacks to collect data and emit log events.
+        # Should only be called when LogStream.emitter is set.
+        #
+        # @return [void]
+        def setup_logging
+          register_logging_callbacks
+        end
+
+        # Extract agent name from delegation tool name
+        #
+        # Converts "DelegateTaskTo[AgentName]" to "agent_name"
+        # Example: "DelegateTaskToWorker" -> "worker"
+        #
+        # @param tool_name [String] Delegation tool name
+        # @return [String] Agent name
+        def extract_delegate_agent_name(tool_name)
+          # Remove "DelegateTaskTo" prefix and lowercase first letter
+          agent_name = tool_name.to_s.sub(/^DelegateTaskTo/, "")
+          # Convert from PascalCase to lowercase (e.g., "Worker" -> "worker", "BackendDev" -> "backendDev")
+          agent_name[0] = agent_name[0].downcase unless agent_name.empty?
+          agent_name
+        end
+
+        # Check if context usage has crossed warning thresholds and emit warnings
+        #
+        # This should be called after each LLM response to check if we've crossed
+        # any warning thresholds (80%, 90%, etc.)
+        #
+        # @return [void]
+        def check_context_warnings
+          current_percentage = @chat.context_usage_percentage
+
+          Context::CONTEXT_WARNING_THRESHOLDS.each do |threshold|
+            # Only warn once per threshold
+            next if @agent_context.warning_threshold_hit?(threshold)
+            next if current_percentage < threshold
+
+            # Mark threshold as hit and emit warning
+            @agent_context.hit_warning_threshold?(threshold)
+
+            LogStream.emit(
+              type: "context_limit_warning",
+              agent: @agent_context.name,
+              model: @chat.model.id,
+              threshold: "#{threshold}%",
+              current_usage: "#{current_percentage}%",
+              tokens_used: @chat.cumulative_total_tokens,
+              tokens_remaining: @chat.tokens_remaining,
+              context_limit: @chat.context_limit,
+              metadata: @agent_context.metadata,
+            )
+          end
+        end
+
+        private
+
+        # Extract usage information from an assistant message
+        #
+        # @param message [RubyLLM::Message] Assistant message with usage data
+        # @return [Hash] Usage information
+        def extract_usage_info(message)
+          cost_info = calculate_cost(message)
+          context_usage = if @chat.respond_to?(:cumulative_input_tokens)
+            {
+              cumulative_input_tokens: @chat.cumulative_input_tokens,
+              cumulative_output_tokens: @chat.cumulative_output_tokens,
+              cumulative_total_tokens: @chat.cumulative_total_tokens,
+              context_limit: @chat.context_limit,
+              tokens_used_percentage: "#{@chat.context_usage_percentage}%",
+              tokens_remaining: @chat.tokens_remaining,
+            }
+          else
+            {}
+          end
+
+          {
+            input_tokens: message.input_tokens,
+            output_tokens: message.output_tokens,
+            total_tokens: (message.input_tokens || 0) + (message.output_tokens || 0),
+            input_cost: cost_info[:input_cost],
+            output_cost: cost_info[:output_cost],
+            total_cost: cost_info[:total_cost],
+          }.merge(context_usage)
+        end
+
+        # Register RubyLLM chat callbacks to collect data and trigger logging
+        #
+        # This sets up low-level RubyLLM callbacks for technical plumbing (tracking state,
+        # collecting tool results), then emits log events via LogStream.
+        #
+        # @return [void]
+        def register_logging_callbacks
+          # Collect tool execution results (technical plumbing)
+          @chat.on_tool_result do |result|
+            @tool_executions << {
+              result: serialize_result(result),
+              completed_at: Time.now.utc.iso8601,
+            }
+          end
+
+          # Track delegations and emit agent_step/agent_stop events
+          @chat.on_end_message do |message|
+            next unless message
+
+            case message.role
+            when :assistant
+              if message.tool_call?
+                # Assistant made tool calls - emit agent_step event
+                trigger_agent_step(message, tool_executions: @tool_executions) if @chat.hook_executor
+                @tool_executions.clear
+              elsif @chat.hook_executor
+                # Final response (finish_reason: "stop") - fire agent_stop
+                trigger_agent_stop(message, tool_executions: @tool_executions)
+              end
+            when :tool
+              # Handle delegation tracking and logging (technical plumbing)
+              if @agent_context.delegation?(call_id: message.tool_call_id)
+                delegate_from = @agent_context.delegation_target(call_id: message.tool_call_id)
+
+                # Emit delegation result log event
+                LogStream.emit(
+                  type: "delegation_result",
+                  agent: @agent_context.name,
+                  delegate_from: delegate_from,
+                  tool_call_id: message.tool_call_id,
+                  result: serialize_result(message.content),
+                  metadata: @agent_context.metadata,
+                )
+
+                @agent_context.clear_delegation(call_id: message.tool_call_id)
+              end
+            end
+          end
+
+          # Track delegations when tool calls are made
+          @chat.on_tool_call do |tool_call|
+            if @agent_context.delegation_tool?(tool_call.name)
+              # Extract agent name from tool name (DelegateTaskTo[AgentName] -> agent_name)
+              agent_name = extract_delegate_agent_name(tool_call.name)
+
+              @agent_context.track_delegation(call_id: tool_call.id, target: agent_name)
+
+              # Emit delegation log event
+              LogStream.emit(
+                type: "agent_delegation",
+                agent: @agent_context.name,
+                tool_call_id: tool_call.id,
+                delegate_to: agent_name,
+                arguments: tool_call.arguments,
+                metadata: @agent_context.metadata,
+              )
+            end
+          end
+        end
+
+        # Trigger agent_step callback
+        #
+        # This fires when the agent makes an intermediate response with tool calls.
+        # The agent hasn't finished yet - it's requesting tools to continue processing.
+        #
+        # @param message [RubyLLM::Message] Assistant message with tool calls
+        # @param tool_executions [Array<Hash>] Tool execution results (should be empty for steps)
+        # @return [void]
+        def trigger_agent_step(message, tool_executions: [])
+          return unless @chat.hook_executor
+
+          usage_info = extract_usage_info(message)
+
+          context = Hooks::Context.new(
+            event: :agent_step,
+            agent_name: @agent_context.name,
+            swarm: @chat.hook_swarm,
+            metadata: {
+              model: message.model_id,
+              content: message.content,
+              tool_calls: format_tool_calls(message.tool_calls),
+              finish_reason: "tool_calls",
+              usage: usage_info,
+              tool_executions: tool_executions.empty? ? nil : tool_executions,
+              timestamp: Time.now.utc.iso8601,
+            },
+          )
+
+          agent_hooks = @chat.hook_agent_hooks[:agent_step] || []
+
+          @chat.hook_executor.execute_safe(
+            event: :agent_step,
+            context: context,
+            callbacks: agent_hooks,
+          )
+        end
+
+        # Trigger agent_stop callback
+        #
+        # This fires when the agent completes with a final response (no more tool calls).
+        #
+        # @param message [RubyLLM::Message] Assistant message with final content
+        # @param tool_executions [Array<Hash>] Tool execution results (if any)
+        # @return [void]
+        def trigger_agent_stop(message, tool_executions: [])
+          return unless @chat.hook_executor
+
+          usage_info = extract_usage_info(message)
+
+          # Use override if set (e.g., "finish_agent"), otherwise default to "stop"
+          finish_reason = @finish_reason_override || "stop"
+          @finish_reason_override = nil # Clear after use
+
+          context = Hooks::Context.new(
+            event: :agent_stop,
+            agent_name: @agent_context.name,
+            swarm: @chat.hook_swarm,
+            metadata: {
+              model: message.model_id,
+              content: message.content,
+              tool_calls: nil, # Final response has no tool calls
+              finish_reason: finish_reason,
+              usage: usage_info,
+              tool_executions: tool_executions.empty? ? nil : tool_executions,
+              timestamp: Time.now.utc.iso8601,
+            },
+          )
+
+          agent_hooks = @chat.hook_agent_hooks[:agent_stop] || []
+
+          @chat.hook_executor.execute_safe(
+            event: :agent_stop,
+            context: context,
+            callbacks: agent_hooks,
+          )
+        end
+      end
+    end
+  end
+end