swarm_memory 2.1.5 → 2.1.6

data/lib/swarm_sdk/hooks/context.rb

@@ -1,197 +0,0 @@
-# frozen_string_literal: true
-
-module SwarmSDK
-  module Hooks
-    # Rich context object passed to hook callbacks
-    #
-    # Provides hooks with comprehensive access to:
-    # - Agent information (name, definition)
-    # - Tool call details (for tool-related events)
-    # - Delegation details (for delegation events)
-    # - Swarm context (access to other agents, configuration)
-    # - Metadata (arbitrary additional data)
-    #
-    # The context is read-write, allowing hooks to modify data
-    # (e.g., add metadata, modify tool parameters).
-    #
-    # @example Access tool call information
-    #   context.tool_call.name  # => "Write"
-    #   context.tool_call.parameters  # => { file_path: "...", content: "..." }
-    #
-    # @example Modify metadata
-    #   context.metadata[:validated] = true
-    #   context.metadata[:validation_time] = Time.now
-    #
-    # @example Check event type
-    #   if context.tool_event?
-    #     validate_tool_call(context.tool_call)
-    #   end
-    class Context
-      attr_reader :event, :agent_name, :agent_definition, :swarm, :metadata
-      attr_accessor :tool_call, :tool_result, :delegation_target, :delegation_result
-
-      # @param event [Symbol] The event type triggering this hook
-      # @param agent_name [String, Symbol] Name of the agent
-      # @param agent_definition [SwarmSDK::AgentDefinition, nil] Agent's configuration
-      # @param swarm [SwarmSDK::Swarm, nil] Reference to the swarm (if available)
-      # @param tool_call [ToolCall, nil] Tool call object (for tool events)
-      # @param tool_result [ToolResult, nil] Tool result (for post_tool_use)
-      # @param delegation_target [String, Symbol, nil] Target agent name (for delegation events)
-      # @param delegation_result [Object, nil] Result from delegation (for post_delegation)
-      # @param metadata [Hash] Additional metadata
-      def initialize(
-        event:,
-        agent_name:,
-        agent_definition: nil,
-        swarm: nil,
-        tool_call: nil,
-        tool_result: nil,
-        delegation_target: nil,
-        delegation_result: nil,
-        metadata: {}
-      )
-        @event = event
-        @agent_name = agent_name
-        @agent_definition = agent_definition
-        @swarm = swarm
-        @tool_call = tool_call
-        @tool_result = tool_result
-        @delegation_target = delegation_target
-        @delegation_result = delegation_result
-        @metadata = metadata
-      end
-
-      # Check if this is a tool-related event
-      #
-      # @return [Boolean] true if event is pre_tool_use or post_tool_use
-      def tool_event?
-        [:pre_tool_use, :post_tool_use].include?(@event)
-      end
-
-      # Check if this is a delegation-related event
-      #
-      # @return [Boolean] true if event is pre_delegation or post_delegation
-      def delegation_event?
-        [:pre_delegation, :post_delegation].include?(@event)
-      end
-
-      # Get tool name (convenience method)
-      #
-      # @return [String, nil] Tool name or nil if not a tool event
-      def tool_name
-        tool_call&.name
-      end
-
-      # Create a copy of this context with modified attributes
-      #
-      # Useful for chaining hooks that need to pass modified context
-      # to subsequent hooks.
-      #
-      # @param attributes [Hash] Attributes to override
-      # @return [Context] New context with modified attributes
-      def with(**attributes)
-        Context.new(
-          event: attributes[:event] || @event,
-          agent_name: attributes[:agent_name] || @agent_name,
-          agent_definition: attributes[:agent_definition] || @agent_definition,
-          swarm: attributes[:swarm] || @swarm,
-          tool_call: attributes[:tool_call] || @tool_call,
-          tool_result: attributes[:tool_result] || @tool_result,
-          delegation_target: attributes[:delegation_target] || @delegation_target,
-          delegation_result: attributes[:delegation_result] || @delegation_result,
-          metadata: attributes[:metadata] || @metadata.dup,
-        )
-      end
-
-      # Convert to hash for logging and debugging
-      #
-      # @return [Hash] Simplified hash representation of context
-      def to_h
-        {
-          event: @event,
-          agent_name: @agent_name,
-          tool_name: tool_name,
-          delegation_target: @delegation_target,
-          metadata: @metadata,
-        }
-      end
-
-      # Convenience methods for creating Results
-      # These allow hooks to use `halt("message")` instead of `SwarmSDK::Hooks::Result.halt("message")`
-
-      # Halt the current operation and return a message
-      #
-      # @param message [String] Message to return
-      # @return [Result] Halt result
-      def halt(message)
-        Result.halt(message)
-      end
-
-      # Replace the current result with a custom value
-      #
-      # @param value [Object] Replacement value
-      # @return [Result] Replace result
-      def replace(value)
-        Result.replace(value)
-      end
-
-      # Reprompt the agent with a new prompt
-      #
-      # @param prompt [String] New prompt
-      # @return [Result] Reprompt result
-      def reprompt(prompt)
-        Result.reprompt(prompt)
-      end
-
-      # Finish the current agent's execution with a final message
-      #
-      # @param message [String] Final message from the agent
-      # @return [Result] Finish agent result
-      def finish_agent(message)
-        Result.finish_agent(message)
-      end
-
-      # Finish the entire swarm execution with a final message
-      #
-      # @param message [String] Final message from the swarm
-      # @return [Result] Finish swarm result
-      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/definition.rb

@@ -1,80 +0,0 @@
-# frozen_string_literal: true
-
-module SwarmSDK
-  module Hooks
-    # Represents a single hook configuration
-    #
-    # A hook definition includes:
-    # - Event type (when to trigger)
-    # - Optional matcher (regex for tool names)
-    # - Priority (execution order)
-    # - Proc to execute
-    #
-    # @example Create a hook definition
-    #   definition = SwarmSDK::Hooks::Definition.new(
-    #     event: :pre_tool_use,
-    #     matcher: "Write|Edit",
-    #     priority: 10,
-    #     proc: ->(ctx) { validate_code(ctx.tool_call) }
-    #   )
-    class Definition
-      attr_reader :event, :matcher, :priority, :proc
-
-      # @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 proc [Proc, Symbol] Hook proc or named hook symbol
-      def initialize(event:, matcher: nil, priority: 0, proc:)
-        @event = event
-        @matcher = compile_matcher(matcher)
-        @priority = priority
-        @proc = proc
-      end
-
-      # Check if this hook should execute for a given tool name
-      #
-      # @param tool_name [String] Name of the tool being called
-      # @return [Boolean] true if hook should execute
-      def matches?(tool_name)
-        return true if @matcher.nil? # No matcher = matches everything
-
-        @matcher.match?(tool_name)
-      end
-
-      # Check if this hook uses a named reference
-      #
-      # @return [Boolean] true if proc is a symbol (named hook)
-      def named_hook?
-        @proc.is_a?(Symbol)
-      end
-
-      # Resolve the actual proc, looking up named hooks if needed
-      #
-      # @param registry [Registry] Registry to lookup named hooks
-      # @return [Proc] The actual proc to execute
-      # @raise [ArgumentError] if named hook not found
-      def resolve_proc(registry)
-        return @proc unless named_hook?
-
-        resolved = registry.get(@proc)
-        raise ArgumentError, "Named hook :#{@proc} not found in registry" unless resolved
-
-        resolved
-      end
-
-      private
-
-      # Compile matcher string/regexp into regexp
-      #
-      # @param matcher [String, Regexp, nil] Matcher pattern
-      # @return [Regexp, nil] Compiled regex or nil
-      def compile_matcher(matcher)
-        return if matcher.nil?
-        return matcher if matcher.is_a?(Regexp)
-
-        # Convert string to regex, treating it as a pattern with | for OR
-        Regexp.new(matcher)
-      end
-    end
-  end
-end

data/lib/swarm_sdk/hooks/error.rb

@@ -1,29 +0,0 @@
-# frozen_string_literal: true
-
-module SwarmSDK
-  module Hooks
-    # Error raised by callbacks to block execution
-    #
-    # This error provides context about which hook failed and includes
-    # the execution context for debugging and error handling.
-    #
-    # @example Raise a hook error to block execution
-    #   raise SwarmSDK::Hooks::Error.new(
-    #     "Validation failed: invalid syntax",
-    #     hook_name: :validate_code,
-    #     context: context
-    #   )
-    class Error < StandardError
-      attr_reader :hook_name, :context
-
-      # @param message [String] Error message
-      # @param hook_name [Symbol, String, nil] Name of the hook that failed
-      # @param context [Context, nil] Execution context when error occurred
-      def initialize(message, hook_name: nil, context: nil)
-        super(message)
-        @hook_name = hook_name
-        @context = context
-      end
-    end
-  end
-end

data/lib/swarm_sdk/hooks/executor.rb

@@ -1,146 +0,0 @@
-# frozen_string_literal: true
-
-module SwarmSDK
-  module Hooks
-    # Executes hooks with proper chaining, error handling, and logging
-    #
-    # The executor:
-    # - Chains multiple hooks for the same event
-    # - Handles errors and blocking (via Error or Result.halt)
-    # - Respects matcher patterns (only runs matching hooks)
-    # - Logs execution for debugging
-    # - Returns Result indicating action to take
-    #
-    # @example Execute hooks
-    #   executor = SwarmSDK::Hooks::Executor.new(registry, logger)
-    #   context = SwarmSDK::Hooks::Context.new(...)
-    #   result = executor.execute(event: :pre_tool_use, context: context, hooks: agent_hooks)
-    #   if result.halt?
-    #     # Handle halt
-    #   elsif result.replace?
-    #     # Use replacement value
-    #   end
-    class Executor
-      # @param registry [Registry] Hook registry for resolving named hooks
-      # @param logger [Logger, nil] Logger for debugging (optional)
-      def initialize(registry, logger: nil)
-        @registry = registry
-        @logger = logger || Logger.new(nil) # Null logger if not provided
-      end
-
-      # Execute all hooks for an event
-      #
-      # Execution order:
-      # 1. Swarm-level defaults (from registry)
-      # 2. Agent-specific hooks
-      # 3. Within each group, by priority (highest first)
-      #
-      # Hooks must return:
-      # - Result - to control execution flow (halt, replace, reprompt, continue)
-      # - nil - treated as continue with unmodified context
-      #
-      # @param event [Symbol] Event type
-      # @param context [Context] Context to pass to hooks
-      # @param callbacks [Array<Definition>] Agent-specific hooks
-      # @return [Result] Result indicating action and value
-      # @raise [Error] If a hook raises an error
-      def execute(event:, context:, callbacks: [])
-        # Combine swarm defaults and agent hooks
-        all_hooks = @registry.get_defaults(event) + callbacks
-
-        # Filter by matcher (for tool events)
-        if context.tool_event? && context.tool_name
-          all_hooks = all_hooks.select { |hook| hook.matches?(context.tool_name) }
-        end
-
-        # Execute hooks in order
-        all_hooks.each do |hook_def|
-          result = execute_single(hook_def, context)
-
-          # Only Result controls flow - nil means continue
-          next unless result.is_a?(Result)
-
-          # Early return for control flow actions
-          return result if result.halt? || result.replace? || result.reprompt? || result.finish_agent? || result.finish_swarm?
-
-          # Update context if continue with modified context
-          context = result.value if result.continue? && result.value.is_a?(Context)
-        end
-
-        # All hooks executed successfully - continue with final context
-        Result.continue(context)
-      rescue Error => e
-        # Re-raise with context for better error messages
-        @logger.error("Hook blocked execution: #{e.message}")
-        raise
-      rescue StandardError => e
-        # Wrap unexpected errors
-        @logger.error("Hook failed unexpectedly: #{e.class} - #{e.message}")
-        @logger.error(e.backtrace.join("\n"))
-        raise Error.new(
-          "Hook failed: #{e.message}",
-          context: context,
-        )
-      end
-
-      # Execute a single hook
-      #
-      # @param hook_def [Definition] Hook to execute
-      # @param context [Context] Current context
-      # @return [Result, nil] Result from hook (Result or nil)
-      # @raise [Error] If hook execution fails
-      def execute_single(hook_def, context)
-        proc = hook_def.resolve_proc(@registry)
-
-        @logger.debug("Executing hook for #{context.event} (agent: #{context.agent_name})")
-
-        # Execute hook with context as parameter
-        # Users can access convenience methods via context parameter:
-        #   hook(:event) { |ctx| ctx.halt("msg") }
-        # This preserves lexical scope and access to surrounding instance variables
-        proc.call(context)
-      rescue Error
-        # Pass through blocking errors
-        raise
-      rescue StandardError => e
-        # Wrap other errors with context and detailed debugging
-        hook_name = hook_def.named_hook? ? hook_def.proc : "anonymous"
-
-        # Log detailed error info for debugging
-        @logger.error("=" * 80)
-        @logger.error("HOOK EXECUTION ERROR")
-        @logger.error("  Hook: #{hook_name}")
-        @logger.error("  Event: #{context.event}")
-        @logger.error("  Agent: #{context.agent_name}")
-        @logger.error("  Proc class: #{proc.class}")
-        @logger.error("  Proc arity: #{proc.arity} (expected: 1 for |context|)")
-        @logger.error("  Error: #{e.class.name}: #{e.message}")
-        @logger.error("  Backtrace:")
-        e.backtrace.first(15).each { |line| @logger.error("    #{line}") }
-        @logger.error("=" * 80)
-
-        raise Error.new(
-          "Hook #{hook_name} failed: #{e.message}",
-          hook_name: hook_name,
-          context: context,
-        )
-      end
-
-      # Execute hooks and return result safely (without raising)
-      #
-      # This is a convenience method that catches Error and converts it
-      # to a halt result, making it easier to use in control flow.
-      #
-      # @param event [Symbol] Event type
-      # @param context [Context] Context to pass to hooks
-      # @param callbacks [Array<Definition>] Agent-specific hooks
-      # @return [Result] Result from hooks
-      def execute_safe(event:, context:, callbacks: [])
-        execute(event: event, context: context, callbacks: callbacks)
-      rescue Error => e
-        @logger.warn("Execution blocked by hook: #{e.message}")
-        Result.halt(e.message)
-      end
-    end
-  end
-end

data/lib/swarm_sdk/hooks/registry.rb

@@ -1,147 +0,0 @@
-# frozen_string_literal: true
-
-module SwarmSDK
-  module Hooks
-    # Central registry for managing named hooks and swarm-level defaults
-    #
-    # The Registry stores:
-    # - Named hooks that can be referenced by symbol in YAML or code
-    # - Swarm-level default hooks that apply to all agents
-    #
-    # @example Register a named hook
-    #   registry = SwarmSDK::Hooks::Registry.new
-    #   registry.register(:validate_code) do |context|
-    #     raise SwarmSDK::Hooks::Error, "Invalid code" unless valid?(context.tool_call)
-    #   end
-    #
-    # @example Add swarm-level default
-    #   registry.add_default(:pre_tool_use, matcher: "Write|Edit") do |context|
-    #     puts "Tool #{context.tool_call.name} called by #{context.agent_name}"
-    #   end
-    class Registry
-      # Available hook event types
-      VALID_EVENTS = [
-        # Swarm lifecycle events
-        :swarm_start,       # When Swarm.execute is called (before first user message)
-        :swarm_stop,        # When Swarm.execute completes (after execution)
-        :first_message,     # When first user message is sent to swarm (Swarm.execute)
-
-        # Agent/LLM events
-        :user_prompt,       # Before sending user message to LLM
-        :agent_step,        # After agent makes intermediate response with tool calls
-        :agent_stop,        # After agent completes with final response (no more tool calls)
-
-        # Tool events
-        :pre_tool_use,      # Before tool execution (can block/modify)
-        :post_tool_use,     # After tool execution
-
-        # Delegation events
-        :pre_delegation,    # Before delegating to another agent
-        :post_delegation,   # After delegation completes
-
-        # 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
-        @named_hooks = {} # { hook_name: proc }
-        @defaults = Hash.new { |h, k| h[k] = [] } # { event_type: [Definition, ...] }
-      end
-
-      # Register a named hook that can be referenced elsewhere
-      #
-      # @param name [Symbol] Unique name for this hook
-      # @param block [Proc] Hook implementation
-      # @raise [ArgumentError] if name already registered or invalid
-      #
-      # @example
-      #   registry.register(:log_tool_use) { |ctx| puts "Tool: #{ctx.tool_call.name}" }
-      def register(name, &block)
-        raise ArgumentError, "Hook name must be a symbol" unless name.is_a?(Symbol)
-        raise ArgumentError, "Hook #{name} already registered" if @named_hooks.key?(name)
-        raise ArgumentError, "Block required" unless block
-
-        @named_hooks[name] = block
-      end
-
-      # Get a named hook by symbol
-      #
-      # @param name [Symbol] Hook name
-      # @return [Proc, nil] The hook proc or nil if not found
-      def get(name)
-        @named_hooks[name]
-      end
-
-      # Add a swarm-level default hook
-      #
-      # These hooks apply to all agents unless overridden at agent level.
-      #
-      # @param event [Symbol] Event type (must be in VALID_EVENTS)
-      # @param matcher [String, Regexp, nil] Optional regex pattern to match tool names
-      # @param priority [Integer] Execution priority (higher runs first)
-      # @param block [Proc] Hook implementation
-      # @raise [ArgumentError] if event invalid or block missing
-      #
-      # @example Add default logging
-      #   registry.add_default(:pre_tool_use) { |ctx| log(ctx) }
-      #
-      # @example Add validation for specific tools
-      #   registry.add_default(:pre_tool_use, matcher: "Write|Edit") do |ctx|
-      #     validate_tool_call(ctx.tool_call)
-      #   end
-      def add_default(event, matcher: nil, priority: 0, &block)
-        validate_event!(event)
-        raise ArgumentError, "Block required" unless block
-
-        definition = Definition.new(
-          event: event,
-          matcher: matcher,
-          priority: priority,
-          proc: block,
-        )
-
-        @defaults[event] << definition
-        @defaults[event].sort_by! { |d| -d.priority } # Higher priority first
-      end
-
-      # Get all default hooks for an event type
-      #
-      # @param event [Symbol] Event type
-      # @return [Array<Definition>] List of hook definitions
-      def get_defaults(event)
-        @defaults[event]
-      end
-
-      # Get all registered named hook names
-      #
-      # @return [Array<Symbol>] List of hook names
-      def named_hooks
-        @named_hooks.keys
-      end
-
-      # Check if a hook name is registered
-      #
-      # @param name [Symbol] Hook name
-      # @return [Boolean] true if registered
-      def registered?(name)
-        @named_hooks.key?(name)
-      end
-
-      private
-
-      # Validate event type
-      #
-      # @param event [Symbol] Event to validate
-      # @raise [ArgumentError] if event invalid
-      def validate_event!(event)
-        return if VALID_EVENTS.include?(event)
-
-        raise ArgumentError, "Invalid event type: #{event}. Valid types: #{VALID_EVENTS.join(", ")}"
-      end
-    end
-  end
-end