swarm_sdk 2.0.0.pre.2

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

@@ -0,0 +1,372 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module Agent
+    class Chat < RubyLLM::Chat
+      # Integrates SwarmSDK's hook system with Agent::Chat
+      #
+      # Responsibilities:
+      # - Setup hook system (registry, executor, agent hooks)
+      # - Provide trigger methods for all hook events
+      # - Wrap ask() to inject user_prompt hooks
+      # - Handle hook results (halt, replace, continue, reprompt)
+      #
+      # This module is included in Agent::Chat and provides methods for triggering hooks.
+      # It overrides ask() to inject user_prompt hooks, but does NOT override
+      # handle_tool_calls (that's handled in Agent::Chat with explicit hook calls).
+      module HookIntegration
+        # Expose hook system components for ContextTracker
+        attr_reader :hook_executor, :hook_swarm, :hook_agent_hooks
+
+        # Setup the hook system for this agent chat
+        #
+        # This must be called after setup_context and before the first ask/complete.
+        # It wires up the hook system to trigger at the right times.
+        #
+        # @param registry [Hooks::Registry] Shared registry for named hooks and swarm defaults
+        # @param agent_definition [Agent::Definition] Agent configuration with hooks
+        # @param swarm [Swarm, nil] Reference to swarm for context
+        # @return [void]
+        def setup_hooks(registry:, agent_definition:, swarm: nil)
+          @hook_registry = registry
+          @hook_swarm = swarm
+          @hook_executor = Hooks::Executor.new(registry, logger: RubyLLM.logger)
+
+          # Extract agent hooks based on format
+          hooks = agent_definition.hooks || {}
+
+          # Check if hooks are pre-parsed HookDefinition objects (from DSL)
+          # or raw YAML hash (to be processed by Hooks::Adapter in pass_5)
+          @hook_agent_hooks = if hooks.is_a?(Hash) && hooks.values.all? { |v| v.is_a?(Array) && v.all? { |item| item.is_a?(Hooks::Definition) } }
+            # DSL hooks - already parsed, use them
+            hooks
+          else
+            # YAML hooks - raw hash, will be processed in pass_5 by Hooks::Adapter
+            # For now, use empty hash (pass_5 will add them later)
+            {}
+          end
+        end
+
+        # Add a hook programmatically at runtime
+        #
+        # This allows agents to add hooks dynamically, which is useful for
+        # implementing adaptive behavior or runtime monitoring.
+        #
+        # @param event [Symbol] Event type (e.g., :pre_tool_use)
+        # @param matcher [String, Regexp, nil] Optional regex pattern for tool names
+        # @param priority [Integer] Execution priority (higher = earlier)
+        # @param block [Proc] Hook implementation
+        def add_hook(event, matcher: nil, priority: 0, &block)
+          raise ArgumentError, "Hooks not set up. Call setup_hooks first." unless @hook_executor
+
+          definition = Hooks::Definition.new(
+            event: event,
+            matcher: matcher,
+            priority: priority,
+            proc: block,
+          )
+
+          @hook_agent_hooks[event] ||= []
+          @hook_agent_hooks[event] << definition
+          @hook_agent_hooks[event].sort_by! { |cb| -cb.priority }
+        end
+
+        # Override ask to trigger user_prompt hooks
+        #
+        # This wraps the Agent::Chat#ask implementation to inject hooks AFTER
+        # system reminders are handled.
+        #
+        # @param prompt [String] User prompt
+        # @param options [Hash] Additional options
+        # @return [RubyLLM::Message] LLM response
+        def ask(prompt, **options)
+          # Trigger user_prompt hook before sending to LLM (can halt or modify prompt)
+          if @hook_executor
+            hook_result = trigger_user_prompt(prompt)
+
+            # Check if hook halted execution
+            if hook_result[:halted]
+              # Return a halted message instead of calling LLM
+              return RubyLLM::Message.new(
+                role: :assistant,
+                content: hook_result[:halt_message],
+                model_id: model.id,
+              )
+            end
+
+            # Use modified prompt if hook provided one (stdout injection)
+            prompt = hook_result[:modified_prompt] if hook_result[:modified_prompt]
+          end
+
+          # Call original ask implementation (Agent::Chat handles system reminders)
+          super(prompt, **options)
+        end
+
+        # Override check_context_warnings to trigger our hook system
+        #
+        # This wraps the default context warning behavior to also trigger hooks.
+        def check_context_warnings
+          return unless respond_to?(:context_usage_percentage)
+
+          current_percentage = 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
+            @agent_context.hit_warning_threshold?(threshold)
+
+            # Emit existing log event (for backward compatibility)
+            LogStream.emit(
+              type: "context_limit_warning",
+              agent: @agent_context.name,
+              model: model.id,
+              threshold: "#{threshold}%",
+              current_usage: "#{current_percentage}%",
+              tokens_used: cumulative_total_tokens,
+              tokens_remaining: tokens_remaining,
+              context_limit: context_limit,
+              metadata: @agent_context.metadata,
+            )
+
+            # Trigger hook system
+            trigger_context_warning(threshold, current_percentage) if @hook_executor
+          end
+        end
+
+        # Trigger pre_tool_use hooks
+        #
+        # Should be called by Agent::Chat before tool execution.
+        # Returns a hash indicating whether to proceed and any custom result.
+        #
+        # @param tool_call [RubyLLM::ToolCall] Tool call from LLM
+        # @return [Hash] { proceed: true/false, custom_result: result (if any) }
+        def trigger_pre_tool_use(tool_call)
+          return { proceed: true } unless @hook_executor
+
+          context = build_hook_context(
+            event: :pre_tool_use,
+            tool_call: wrap_tool_call_to_hooks(tool_call),
+          )
+
+          agent_hooks = @hook_agent_hooks[:pre_tool_use] || []
+
+          result = @hook_executor.execute_safe(
+            event: :pre_tool_use,
+            context: context,
+            callbacks: agent_hooks,
+          )
+
+          # Return custom result if hook provides one
+          if result.replace?
+            { proceed: false, custom_result: result.value }
+          elsif result.halt?
+            { proceed: false, custom_result: result.value || "Tool execution blocked by hook" }
+          elsif result.finish_agent?
+            # Finish agent execution immediately with this message
+            { proceed: false, finish_agent: true, custom_result: result.value }
+          elsif result.finish_swarm?
+            # Finish entire swarm execution immediately with this message
+            { proceed: false, finish_swarm: true, custom_result: result.value }
+          else
+            { proceed: true }
+          end
+        end
+
+        # Trigger post_tool_use hooks
+        #
+        # Should be called by Agent::Chat after tool execution.
+        # Returns modified result if hook replaces it, or a special marker for finish actions.
+        #
+        # @param result [String, Object] Tool execution result
+        # @param tool_call [RubyLLM::ToolCall] Tool call object with full context
+        # @return [Object, Hash] Modified result if hook replaces it, hash with :finish_agent or :finish_swarm if finishing, otherwise original result
+        def trigger_post_tool_use(result, tool_call:)
+          return result unless @hook_executor
+
+          context = build_hook_context(
+            event: :post_tool_use,
+            tool_result: wrap_tool_result(tool_call.id, tool_call.name, result),
+          )
+
+          agent_hooks = @hook_agent_hooks[:post_tool_use] || []
+
+          hook_result = @hook_executor.execute_safe(
+            event: :post_tool_use,
+            context: context,
+            callbacks: agent_hooks,
+          )
+
+          # Return modified result or finish markers
+          if hook_result.replace?
+            hook_result.value
+          elsif hook_result.finish_agent?
+            { __finish_agent__: true, message: hook_result.value }
+          elsif hook_result.finish_swarm?
+            { __finish_swarm__: true, message: hook_result.value }
+          else
+            result
+          end
+        end
+
+        private
+
+        # Trigger context_warning hooks
+        #
+        # Hooks have access to the chat instance via metadata[:chat]
+        # to access and manipulate the messages array.
+        #
+        # @param threshold [Integer] Warning threshold percentage
+        # @param current_usage [Float] Current usage percentage
+        # @return [void]
+        def trigger_context_warning(threshold, current_usage)
+          return unless @hook_executor
+
+          context = build_hook_context(
+            event: :context_warning,
+            metadata: {
+              chat: self, # Provide access to chat instance (for messages array)
+              threshold: threshold,
+              percentage: current_usage,
+              tokens_used: cumulative_total_tokens,
+              tokens_remaining: tokens_remaining,
+              context_limit: context_limit,
+            },
+          )
+
+          agent_hooks = @hook_agent_hooks[:context_warning] || []
+
+          @hook_executor.execute_safe(
+            event: :context_warning,
+            context: context,
+            callbacks: agent_hooks,
+          )
+        end
+
+        # Trigger user_prompt hooks
+        #
+        # This fires before sending a user message to the LLM.
+        # Can halt execution or append hook stdout to prompt.
+        #
+        # @param prompt [String] User's message/prompt
+        # @return [Hash] { halted: bool, halt_message: String, modified_prompt: String }
+        def trigger_user_prompt(prompt)
+          return { halted: false, modified_prompt: prompt } unless @hook_executor
+
+          # Filter out delegation tools from tools list
+          actual_tools = if respond_to?(:tools) && @agent_context
+            tools.keys.reject { |tool_name| @agent_context.delegation_tool?(tool_name.to_s) }
+          else
+            []
+          end
+
+          # Extract agent names from delegation tool names
+          delegate_agents = if @agent_context&.delegation_tools
+            @agent_context.delegation_tools.map { |tool_name| @context_tracker.extract_delegate_agent_name(tool_name) }
+          else
+            []
+          end
+
+          context = build_hook_context(
+            event: :user_prompt,
+            metadata: {
+              prompt: prompt,
+              message_count: messages.size,
+              model: model.id,
+              provider: model.provider,
+              tools: actual_tools,
+              delegates_to: delegate_agents,
+              timestamp: Time.now.utc.iso8601,
+            },
+          )
+
+          agent_hooks = @hook_agent_hooks[:user_prompt] || []
+
+          result = @hook_executor.execute_safe(
+            event: :user_prompt,
+            context: context,
+            callbacks: agent_hooks,
+          )
+
+          # Handle hook result
+          if result.halt?
+            # Hook blocked execution
+            { halted: true, halt_message: result.value }
+          elsif result.replace?
+            # Hook provided stdout to append to prompt (exit code 0)
+            modified_prompt = "#{prompt}\n\n<hook-context>\n#{result.value}\n</hook-context>"
+            { halted: false, modified_prompt: modified_prompt }
+          else
+            # Normal continue
+            { halted: false, modified_prompt: prompt }
+          end
+        end
+
+        # Build a hook context object
+        #
+        # @param event [Symbol] Event type
+        # @param tool_call [Hooks::ToolCall, nil] Tool call object
+        # @param tool_result [Hooks::ToolResult, nil] Tool result object
+        # @param metadata [Hash] Additional metadata
+        # @return [Hooks::Context] Context object
+        def build_hook_context(event:, tool_call: nil, tool_result: nil, metadata: {})
+          Hooks::Context.new(
+            event: event,
+            agent_name: @agent_context&.name || "unknown",
+            agent_definition: nil, # Could store this in setup_hooks if needed
+            swarm: @hook_swarm,
+            tool_call: tool_call,
+            tool_result: tool_result,
+            metadata: metadata,
+          )
+        end
+
+        # Wrap a RubyLLM tool call in our Hooks::ToolCall value object
+        #
+        # @param tool_call [RubyLLM::ToolCall] RubyLLM tool call
+        # @return [Hooks::ToolCall] Our wrapped tool call
+        def wrap_tool_call_to_hooks(tool_call)
+          Hooks::ToolCall.new(
+            id: tool_call.id,
+            name: tool_call.name,
+            parameters: tool_call.arguments,
+          )
+        end
+
+        # Wrap a tool result in our Hooks::ToolResult value object
+        #
+        # @param tool_call_id [String] Tool call ID
+        # @param tool_name [String] Tool name
+        # @param result [Object] Tool execution result
+        # @return [Hooks::ToolResult] Our wrapped result
+        def wrap_tool_result(tool_call_id, tool_name, result)
+          success = !result.is_a?(StandardError)
+          error = result.is_a?(StandardError) ? result.message : nil
+
+          Hooks::ToolResult.new(
+            tool_call_id: tool_call_id,
+            tool_name: tool_name,
+            content: success ? result : nil,
+            success: success,
+            error: error,
+          )
+        end
+
+        # Check if a tool call is a delegation tool
+        #
+        # Delegation tools fire their own pre_delegation/post_delegation events
+        # and should NOT fire pre_tool_use/post_tool_use events.
+        #
+        # @param tool_call [RubyLLM::ToolCall] Tool call to check
+        # @return [Boolean] true if this is a delegation tool
+        def delegation_tool_call?(tool_call)
+          return false unless @agent_context
+
+          @agent_context.delegation_tool?(tool_call.name)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module Agent
+    class Chat < RubyLLM::Chat
+      # Helper methods for logging and serialization of tool calls and results
+      #
+      # Responsibilities:
+      # - Format tool calls for logging
+      # - Serialize tool results (handling different types)
+      # - Calculate LLM costs based on token usage
+      #
+      # These are stateless utility methods that operate on data structures.
+      module LoggingHelpers
+        # Format tool calls for logging
+        #
+        # @param tool_calls_hash [Hash] Tool calls from message
+        # @return [Array<Hash>, nil] Formatted tool calls
+        def format_tool_calls(tool_calls_hash)
+          return unless tool_calls_hash
+
+          tool_calls_hash.map do |_id, tc|
+            {
+              id: tc.id,
+              name: tc.name,
+              arguments: tc.arguments,
+            }
+          end
+        end
+
+        # Serialize a tool result for logging
+        #
+        # Handles multiple result types:
+        # - String: pass through
+        # - Hash/Array: pass through
+        # - RubyLLM::Content: extract text and attachment info
+        # - Other: convert to string
+        #
+        # @param result [String, Hash, Array, RubyLLM::Content, Object] Tool result
+        # @return [String, Hash, Array] Serialized result
+        def serialize_result(result)
+          case result
+          when String then result
+          when Hash, Array then result
+          when RubyLLM::Content
+            # Format Content objects to show text and attachment info
+            parts = []
+            parts << result.text if result.text && !result.text.empty?
+
+            if result.attachments.any?
+              attachment_info = result.attachments.map do |att|
+                "#{att.source} (#{att.mime_type})"
+              end.join(", ")
+              parts << "[Attachments: #{attachment_info}]"
+            end
+
+            parts.join(" ")
+          else
+            result.to_s
+          end
+        end
+
+        # Calculate LLM cost for a message
+        #
+        # Uses RubyLLM's model registry to get pricing information.
+        # Returns zero cost if pricing is unavailable.
+        #
+        # @param message [RubyLLM::Message] Message with token counts
+        # @return [Hash] Cost breakdown { input_cost:, output_cost:, total_cost: }
+        def calculate_cost(message)
+          return zero_cost unless message.input_tokens && message.output_tokens
+
+          model_info = RubyLLM.models.find(message.model_id)
+          return zero_cost unless model_info
+
+          # Prices are per million tokens (USD)
+          input_cost = (message.input_tokens / 1_000_000.0) * model_info.input_price_per_million
+          output_cost = (message.output_tokens / 1_000_000.0) * model_info.output_price_per_million
+
+          {
+            input_cost: input_cost,
+            output_cost: output_cost,
+            total_cost: input_cost + output_cost,
+          }
+        rescue StandardError
+          # Model not found in registry or pricing not available
+          zero_cost
+        end
+
+        # Zero cost fallback
+        #
+        # @return [Hash] Zero cost breakdown
+        def zero_cost
+          { input_cost: 0.0, output_cost: 0.0, total_cost: 0.0 }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module Agent
+    class Chat < RubyLLM::Chat
+      # Handles injection of system reminders at strategic points in the conversation
+      #
+      # Responsibilities:
+      # - Inject reminders before/after first user message
+      # - Inject periodic TodoWrite reminders
+      # - Track when reminders were last injected
+      #
+      # This class is stateless - it operates on the chat's message history.
+      class SystemReminderInjector
+        # System reminder to inject BEFORE the first user message
+        BEFORE_FIRST_MESSAGE_REMINDER = <<~REMINDER.strip
+          <system-reminder>
+          As you answer the user's questions, you can use the following context:
+
+          # important-instruction-reminders
+
+          Do what has been asked; nothing more, nothing less.
+          NEVER create files unless they're absolutely necessary for achieving your goal.
+          ALWAYS prefer editing an existing file to creating a new one.
+          NEVER proactively create documentation files (*.md) or README files. Only create documentation files if explicitly requested by the User.
+
+          IMPORTANT: this context may or may not be relevant to your tasks. You should not respond to this context unless it is highly relevant to your task.
+
+          </system-reminder>
+        REMINDER
+
+        # System reminder to inject AFTER the first user message
+        AFTER_FIRST_MESSAGE_REMINDER = <<~REMINDER.strip
+          <system-reminder>Your todo list is currently empty. DO NOT mention this to the user. If this task requires multiple steps: (1) FIRST analyze the scope by searching/reading files, (2) SECOND create a COMPLETE todo list with ALL tasks before starting work, (3) THIRD execute tasks one by one. Only skip the todo list for simple single-step tasks. Do not mention this message to the user.</system-reminder>
+        REMINDER
+
+        # Periodic reminder about TodoWrite tool usage
+        TODOWRITE_PERIODIC_REMINDER = <<~REMINDER.strip
+          <system-reminder>The TodoWrite tool hasn't been used recently. If you're working on tasks that would benefit from tracking progress, consider using the TodoWrite tool to track progress. Also consider cleaning up the todo list if has become stale and no longer matches what you are working on. Only use it if it's relevant to the current work. This is just a gentle reminder - ignore if not applicable.</system-reminder>
+        REMINDER
+
+        # Number of messages between TodoWrite reminders
+        TODOWRITE_REMINDER_INTERVAL = 8
+
+        class << self
+          # Check if this is the first user message in the conversation
+          #
+          # @param chat [Agent::Chat] The chat instance
+          # @return [Boolean] true if no user messages exist yet
+          def first_message?(chat)
+            chat.messages.none? { |msg| msg.role == :user }
+          end
+
+          # Inject first message reminders (before + after user message)
+          #
+          # This manually constructs the first message sequence with system reminders
+          # sandwiching the actual user prompt.
+          #
+          # @param chat [Agent::Chat] The chat instance
+          # @param prompt [String] The user's actual prompt
+          # @return [void]
+          def inject_first_message_reminders(chat, prompt)
+            chat.add_message(role: :user, content: BEFORE_FIRST_MESSAGE_REMINDER)
+            chat.add_message(role: :user, content: prompt)
+            chat.add_message(role: :user, content: AFTER_FIRST_MESSAGE_REMINDER)
+          end
+
+          # Check if we should inject a periodic TodoWrite reminder
+          #
+          # Injects a reminder if:
+          # 1. Enough messages have passed (>= 5)
+          # 2. TodoWrite hasn't been used in the last TODOWRITE_REMINDER_INTERVAL messages
+          #
+          # @param chat [Agent::Chat] The chat instance
+          # @param last_todowrite_index [Integer, nil] Index of last TodoWrite usage
+          # @return [Boolean] true if reminder should be injected
+          def should_inject_todowrite_reminder?(chat, last_todowrite_index)
+            # Need at least a few messages before reminding
+            return false if chat.messages.count < 5
+
+            # Find the last message that contains TodoWrite tool usage
+            last_todo_index = chat.messages.rindex do |msg|
+              msg.role == :tool && msg.content.to_s.include?("TodoWrite")
+            end
+
+            # Check if enough messages have passed since last TodoWrite
+            if last_todo_index.nil? && last_todowrite_index.nil?
+              # Never used TodoWrite - check if we've exceeded interval
+              chat.messages.count >= TODOWRITE_REMINDER_INTERVAL
+            elsif last_todo_index
+              # Recently used - don't remind
+              false
+            elsif last_todowrite_index
+              # Used before - check if interval has passed
+              chat.messages.count - last_todowrite_index >= TODOWRITE_REMINDER_INTERVAL
+            else
+              false
+            end
+          end
+
+          # Update the last TodoWrite index by finding it in messages
+          #
+          # @param chat [Agent::Chat] The chat instance
+          # @return [Integer, nil] Index of last TodoWrite usage, or nil
+          def find_last_todowrite_index(chat)
+            chat.messages.rindex do |msg|
+              msg.role == :tool && msg.content.to_s.include?("TodoWrite")
+            end
+          end
+        end
+      end
+    end
+  end
+end