swarm_memory 2.1.4 → 2.1.6

data/lib/swarm_sdk/hooks/result.rb

@@ -1,150 +0,0 @@
-# frozen_string_literal: true
-
-module SwarmSDK
-  module Hooks
-    # Result object returned by hooks to control execution flow
-    #
-    # Hooks can return a Result to:
-    # - Continue normal execution (default)
-    # - Halt execution and return an error/message
-    # - Replace a value (e.g., tool result, delegation result)
-    # - Reprompt the agent with a new prompt
-    # - Finish the current agent's execution (agent scope)
-    # - Finish the entire swarm execution (swarm scope)
-    #
-    # @example Continue normal execution (default)
-    #   SwarmSDK::Hooks::Result.continue
-    #
-    # @example Halt execution with error message
-    #   SwarmSDK::Hooks::Result.halt("Validation failed: invalid input")
-    #
-    # @example Replace tool result
-    #   SwarmSDK::Hooks::Result.replace("Custom tool result")
-    #
-    # @example Reprompt agent with modified prompt
-    #   SwarmSDK::Hooks::Result.reprompt("Modified task: #{original_task}")
-    #
-    # @example Finish current agent with message
-    #   SwarmSDK::Hooks::Result.finish_agent("Agent task completed")
-    #
-    # @example Finish entire swarm with message
-    #   SwarmSDK::Hooks::Result.finish_swarm("All tasks complete!")
-    class Result
-      attr_reader :action, :value
-
-      # Valid actions that control execution flow
-      VALID_ACTIONS = [:continue, :halt, :replace, :reprompt, :finish_agent, :finish_swarm].freeze
-
-      # @param action [Symbol] Action to take (:continue, :halt, :replace, :reprompt)
-      # @param value [Object, nil] Associated value (context for :continue, message for :halt, etc.)
-      def initialize(action:, value: nil)
-        unless VALID_ACTIONS.include?(action)
-          raise ArgumentError, "Invalid action: #{action}. Valid actions: #{VALID_ACTIONS.join(", ")}"
-        end
-
-        @action = action
-        @value = value
-      end
-
-      # Check if this result indicates halting execution
-      #
-      # @return [Boolean] true if action is :halt
-      def halt?
-        @action == :halt
-      end
-
-      # Check if this result provides a replacement value
-      #
-      # @return [Boolean] true if action is :replace
-      def replace?
-        @action == :replace
-      end
-
-      # Check if this result requests reprompting
-      #
-      # @return [Boolean] true if action is :reprompt
-      def reprompt?
-        @action == :reprompt
-      end
-
-      # Check if this result continues normal execution
-      #
-      # @return [Boolean] true if action is :continue
-      def continue?
-        @action == :continue
-      end
-
-      # Check if this result finishes the current agent
-      #
-      # @return [Boolean] true if action is :finish_agent
-      def finish_agent?
-        @action == :finish_agent
-      end
-
-      # Check if this result finishes the entire swarm
-      #
-      # @return [Boolean] true if action is :finish_swarm
-      def finish_swarm?
-        @action == :finish_swarm
-      end
-
-      class << self
-        # Create a result that continues normal execution
-        #
-        # @param context [Context, nil] Updated context (optional)
-        # @return [Result] Result with continue action
-        def continue(context = nil)
-          new(action: :continue, value: context)
-        end
-
-        # Create a result that halts execution
-        #
-        # @param message [String] Error or halt message
-        # @return [Result] Result with halt action
-        def halt(message)
-          new(action: :halt, value: message)
-        end
-
-        # Create a result that replaces a value
-        #
-        # @param value [Object] Replacement value
-        # @return [Result] Result with replace action
-        def replace(value)
-          new(action: :replace, value: value)
-        end
-
-        # Create a result that reprompts the agent
-        #
-        # @param prompt [String] New prompt to send to agent
-        # @return [Result] Result with reprompt action
-        def reprompt(prompt)
-          new(action: :reprompt, value: prompt)
-        end
-
-        # Create a result that finishes the current agent
-        #
-        # Exits the agent's chat loop and returns the message as the agent's
-        # final response. If this agent was delegated to, control returns to
-        # the calling agent. The swarm continues if there's more work.
-        #
-        # @param message [String] Final message from the agent
-        # @return [Result] Result with finish_agent action
-        def finish_agent(message)
-          new(action: :finish_agent, value: message)
-        end
-
-        # Create a result that finishes the entire swarm
-        #
-        # Immediately exits the Swarm.execute() loop and returns the message
-        # as the final Result#output. All agent execution stops and the user
-        # receives this message.
-        #
-        # @param message [String] Final message from the swarm
-        # @return [Result] Result with finish_swarm action
-        def finish_swarm(message)
-          new(action: :finish_swarm, value: message)
-        end
-      end
-    end
-  end
-end

data/lib/swarm_sdk/hooks/shell_executor.rb

@@ -1,255 +0,0 @@
-# frozen_string_literal: true
-
-require "open3"
-require "json"
-require "timeout"
-
-module SwarmSDK
-  module Hooks
-    # Executes shell command hooks with JSON I/O and exit code handling
-    #
-    # ShellExecutor runs external shell commands (defined in YAML hooks) and
-    # converts their exit codes to Result objects that control execution flow.
-    #
-    # ## Exit Code Behavior (following Claude Code convention)
-    #
-    # - **0**: Success - continue execution (Result.continue)
-    # - **2**: Block with error feedback to LLM (Result.halt)
-    # - **Other**: Non-blocking error - log warning and continue (Result.continue)
-    #
-    # ## JSON I/O Format
-    #
-    # **stdin (to hook script)**:
-    # ```json
-    # {
-    #   "event": "pre_tool_use",
-    #   "agent": "backend",
-    #   "tool": "Write",
-    #   "parameters": { "file_path": "api.rb", "content": "..." }
-    # }
-    # ```
-    #
-    # **stdout (from hook script)**:
-    # ```json
-    # {
-    #   "success": false,
-    #   "error": "Validation failed: syntax error"
-    # }
-    # ```
-    #
-    # @example Execute a validation hook
-    #   result = SwarmSDK::Hooks::ShellExecutor.execute(
-    #     command: "python scripts/validate.py",
-    #     input_json: { event: "pre_tool_use", tool: "Write", parameters: {...} },
-    #     timeout: 10,
-    #     agent_name: :backend,
-    #     swarm_name: "Dev Team"
-    #   )
-    #   # => Result (continue or halt based on exit code)
-    class ShellExecutor
-      # Backward compatibility alias - use Defaults module for new code
-      DEFAULT_TIMEOUT = Defaults::Timeouts::HOOK_SHELL_SECONDS
-
-      class << self
-        # Execute a shell command hook
-        #
-        # @param command [String] Shell command to execute
-        # @param input_json [Hash] JSON data to provide on stdin
-        # @param timeout [Integer] Timeout in seconds (default: 60)
-        # @param agent_name [Symbol, String, nil] Agent name for environment variables
-        # @param swarm_name [String, nil] Swarm name for environment variables
-        # @param event [Symbol] Event type for context-aware behavior
-        # @return [Result] Result based on exit code (continue or halt)
-        def execute(command:, input_json:, timeout: DEFAULT_TIMEOUT, agent_name: nil, swarm_name: nil, event: nil)
-          # Build environment variables
-          env = build_environment(agent_name: agent_name, swarm_name: swarm_name)
-
-          # Execute command with JSON stdin and timeout
-          stdout, stderr, status = Timeout.timeout(timeout) do
-            Open3.capture3(
-              env,
-              command,
-              stdin_data: JSON.generate(input_json),
-            )
-          end
-
-          # Handle exit code per Claude Code convention (context-aware)
-          result = handle_exit_code(status.exitstatus, stdout, stderr, event)
-
-          # Emit log event for hook execution
-          case status.exitstatus
-          when 0
-            # Success - log stdout/stderr
-            emit_hook_log(
-              event: event,
-              agent_name: agent_name,
-              command: command,
-              exit_code: status.exitstatus,
-              success: true,
-              stdout: stdout,
-              stderr: stderr,
-            )
-          when 2
-            # Blocking error - always log stderr
-            emit_hook_log(
-              event: event,
-              agent_name: agent_name,
-              command: command,
-              exit_code: status.exitstatus,
-              success: false,
-              stderr: stderr,
-              blocked: true,
-            )
-          else
-            # Non-blocking error - log stderr
-            emit_hook_log(
-              event: event,
-              agent_name: agent_name,
-              command: command,
-              exit_code: status.exitstatus,
-              success: false,
-              stderr: stderr,
-              blocked: false,
-            )
-          end
-
-          result
-        rescue Timeout::Error
-          emit_hook_log(
-            event: event,
-            agent_name: agent_name,
-            command: command,
-            exit_code: nil,
-            success: false,
-            stderr: "Timeout after #{timeout}s",
-          )
-          # Don't block on timeout - log and continue
-          Result.continue
-        rescue StandardError => e
-          emit_hook_log(
-            event: event,
-            agent_name: agent_name,
-            command: command,
-            exit_code: nil,
-            success: false,
-            stderr: e.message,
-          )
-          # Don't block on errors - log and continue
-          Result.continue
-        end
-
-        private
-
-        # Build environment variables for hook execution
-        #
-        # @param agent_name [Symbol, String, nil] Agent name
-        # @param swarm_name [String, nil] Swarm name
-        # @return [Hash] Environment variables
-        def build_environment(agent_name:, swarm_name:)
-          {
-            "SWARM_SDK_PROJECT_DIR" => Dir.pwd,
-            "SWARM_SDK_AGENT_NAME" => agent_name.to_s,
-            "SWARM_SDK_SWARM_NAME" => swarm_name.to_s,
-            "PATH" => ENV.fetch("PATH", ""),
-          }
-        end
-
-        # Handle exit code and return appropriate Result
-        #
-        # @param exit_code [Integer] Process exit code
-        # @param stdout [String] Standard output
-        # @param stderr [String] Standard error
-        # @param event [Symbol] Hook event type
-        # @return [Result] Result based on exit code
-        def handle_exit_code(exit_code, stdout, stderr, event)
-          case exit_code
-          when 0
-            # Success - continue execution
-            # For user_prompt and swarm_start: return stdout to be shown to agent
-            if [:user_prompt, :swarm_start].include?(event) && !stdout.strip.empty?
-              # Return Result with stdout that will be appended to prompt
-              Result.replace(stdout.strip)
-            else
-              # Normal success
-              Result.continue
-            end
-          when 2
-            # Blocking error - behavior depends on event type
-            handle_exit_code_2(event, stdout, stderr)
-          else
-            # Non-blocking error - continue (stderr logged above)
-            Result.continue
-          end
-        end
-
-        # Handle exit code 2 (blocking error)
-        #
-        # @param event [Symbol] Hook event type
-        # @param _stdout [String] Standard output (unused)
-        # @param stderr [String] Standard error
-        # @return [Result] Result based on event type
-        def handle_exit_code_2(event, _stdout, stderr)
-          error_msg = stderr.strip
-
-          case event
-          when :pre_tool_use
-            # Block tool call, show stderr to agent (stderr already logged above)
-            Result.halt(error_msg)
-          when :post_tool_use
-            # Tool already ran, show stderr to agent (stderr already logged above)
-            Result.halt(error_msg)
-          when :user_prompt
-            # Block prompt processing, erase prompt
-            # stderr is logged (above) for user to see, but NOT shown to agent
-            # Return empty halt (prompt is erased, no message to agent)
-            Result.halt("")
-          when :agent_stop
-            # Block stoppage, show stderr to agent (stderr already logged above)
-            Result.halt(error_msg)
-          when :context_warning, :swarm_start, :swarm_stop
-            # N/A - stderr logged above, don't halt
-            Result.continue
-          else
-            # Default: halt with stderr
-            Result.halt(error_msg)
-          end
-        end
-
-        # Emit hook execution log entry
-        #
-        # @param event [Symbol] Hook event type
-        # @param agent_name [String, Symbol, nil] Agent name
-        # @param command [String] Shell command executed
-        # @param exit_code [Integer, nil] Process exit code
-        # @param success [Boolean] Whether execution succeeded
-        # @param stdout [String, nil] Standard output
-        # @param stderr [String, nil] Standard error
-        # @param blocked [Boolean] Whether execution was blocked (exit code 2)
-        def emit_hook_log(event:, agent_name:, command:, exit_code:, success:, stdout: nil, stderr: nil, blocked: false)
-          # Only emit if LogStream is enabled (has emitter)
-          return unless LogStream.enabled?
-
-          log_entry = {
-            type: "hook_executed",
-            hook_event: event&.to_s, # Which hook event triggered this (pre_tool_use, swarm_start, etc.)
-            agent: agent_name,
-            command: command,
-            exit_code: exit_code,
-            success: success,
-          }
-
-          # Add stdout if present (exit code 0)
-          log_entry[:stdout] = stdout.strip if stdout && !stdout.strip.empty?
-
-          # Add stderr if present (any exit code)
-          log_entry[:stderr] = stderr.strip if stderr && !stderr.strip.empty?
-
-          # Add blocked flag for exit code 2
-          log_entry[:blocked] = true if blocked
-
-          LogStream.emit(**log_entry)
-        end
-      end
-    end
-  end
-end

data/lib/swarm_sdk/hooks/tool_call.rb

@@ -1,35 +0,0 @@
-# frozen_string_literal: true
-
-module SwarmSDK
-  module Hooks
-    # Represents a tool call in the hooks system
-    #
-    # This is a simple value object that wraps tool call information
-    # from RubyLLM in a consistent, immutable format for hooks.
-    #
-    # @example Access tool call information in a hook
-    #   swarm.add_callback(:pre_tool_use) do |context|
-    #     puts "Tool: #{context.tool_call.name}"
-    #     puts "Parameters: #{context.tool_call.parameters.inspect}"
-    #   end
-    class ToolCall
-      attr_reader :id, :name, :parameters
-
-      # @param id [String] Unique identifier for this tool call
-      # @param name [String] Name of the tool being called
-      # @param parameters [Hash] Parameters passed to the tool
-      def initialize(id:, name:, parameters:)
-        @id = id
-        @name = name
-        @parameters = parameters
-      end
-
-      # Convert to hash representation
-      #
-      # @return [Hash] Hash with id, name, and parameters
-      def to_h
-        { id: @id, name: @name, parameters: @parameters }
-      end
-    end
-  end
-end

data/lib/swarm_sdk/hooks/tool_result.rb

@@ -1,62 +0,0 @@
-# frozen_string_literal: true
-
-module SwarmSDK
-  module Hooks
-    # Represents the result of a tool execution
-    #
-    # This is a simple value object that wraps tool execution results
-    # in a consistent format for post-tool-use hooks.
-    #
-    # @example Access tool result in a hook
-    #   swarm.add_callback(:post_tool_use) do |context|
-    #     if context.tool_result.success?
-    #       puts "Tool succeeded: #{context.tool_result.content}"
-    #     else
-    #       puts "Tool failed: #{context.tool_result.error}"
-    #     end
-    #   end
-    class ToolResult
-      attr_reader :tool_call_id, :tool_name, :content, :success, :error
-
-      # @param tool_call_id [String] ID of the tool call this result corresponds to
-      # @param tool_name [String] Name of the tool that was executed
-      # @param content [String, nil] Result content (if successful)
-      # @param success [Boolean] Whether the tool execution succeeded
-      # @param error [String, nil] Error message (if failed)
-      def initialize(tool_call_id:, tool_name:, content: nil, success: true, error: nil)
-        @tool_call_id = tool_call_id
-        @tool_name = tool_name
-        @content = content
-        @success = success
-        @error = error
-      end
-
-      # Check if the tool execution succeeded
-      #
-      # @return [Boolean] true if successful
-      def success?
-        @success
-      end
-
-      # Check if the tool execution failed
-      #
-      # @return [Boolean] true if failed
-      def failure?
-        !@success
-      end
-
-      # Convert to hash representation
-      #
-      # @return [Hash] Hash with all result attributes
-      def to_h
-        {
-          tool_call_id: @tool_call_id,
-          tool_name: @tool_name,
-          content: @content,
-          success: @success,
-          error: @error,
-        }
-      end
-    end
-  end
-end