swarm_sdk 2.7.14 → 3.0.0.alpha2

data/lib/swarm_sdk/v3/hooks/context.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module V3
+    module Hooks
+      # Read-only context passed to hook blocks
+      #
+      # Each hook event type populates a different subset of fields:
+      #
+      # | Field           | before_ask | after_ask | before_tool | after_tool | on_stop |
+      # |-----------------|------------|-----------|-------------|------------|---------|
+      # | event           | yes        | yes       | yes         | yes        | yes     |
+      # | agent_name      | yes        | yes       | yes         | yes        | yes     |
+      # | prompt          | yes        | yes       | -           | -          | -       |
+      # | response        | -          | yes       | -           | -          | yes     |
+      # | tool_name       | -          | -         | yes         | yes        | -       |
+      # | tool_arguments  | -          | -         | yes         | yes        | -       |
+      # | tool_result     | -          | -         | -           | yes        | -       |
+      #
+      # Hook blocks use convenience methods to return {Result} objects:
+      #
+      # @example Halt processing
+      #   before_ask { |ctx| ctx.halt("Not allowed") }
+      #
+      # @example Replace a value
+      #   after_tool { |ctx| ctx.replace(sanitize(ctx.tool_result)) }
+      #
+      # @example Continue normally (explicit)
+      #   before_tool { |ctx| ctx.continue }
+      class Context
+        # @return [Symbol] Event type (:before_ask, :after_ask, :before_tool, :after_tool, :on_stop)
+        attr_reader :event
+
+        # @return [Symbol] Agent name from definition
+        attr_reader :agent_name
+
+        # @return [String, nil] User prompt (ask events only)
+        attr_reader :prompt
+
+        # @return [RubyLLM::Message, nil] LLM response (after_ask and on_stop only)
+        attr_reader :response
+
+        # @return [String, nil] Tool name (tool events only)
+        attr_reader :tool_name
+
+        # @return [Hash, nil] Tool call arguments (tool events only)
+        attr_reader :tool_arguments
+
+        # @return [Object, nil] Tool execution result (after_tool only)
+        attr_reader :tool_result
+
+        # Create a new hook context
+        #
+        # @param event [Symbol] Event type
+        # @param agent_name [Symbol] Agent identifier
+        # @param prompt [String, nil] User prompt
+        # @param response [RubyLLM::Message, nil] LLM response
+        # @param tool_name [String, nil] Tool name
+        # @param tool_arguments [Hash, nil] Tool arguments
+        # @param tool_result [Object, nil] Tool result
+        def initialize(event:, agent_name:, prompt: nil, response: nil, tool_name: nil, tool_arguments: nil, tool_result: nil)
+          @event = event
+          @agent_name = agent_name
+          @prompt = prompt
+          @response = response
+          @tool_name = tool_name
+          @tool_arguments = tool_arguments
+          @tool_result = tool_result
+          freeze
+        end
+
+        # Signal to continue normal processing
+        #
+        # @return [Result] A continue result
+        #
+        # @example
+        #   before_ask { |ctx| ctx.continue }
+        def continue
+          Result.continue
+        end
+
+        # Signal to halt processing
+        #
+        # @param message [String, nil] Optional halt message
+        # @return [Result] A halt result
+        #
+        # @example Block tool execution
+        #   before_tool { |ctx| ctx.halt("Tool disabled") }
+        #
+        # @example Abort ask
+        #   before_ask { |ctx| ctx.halt }
+        def halt(message = nil)
+          Result.halt(message)
+        end
+
+        # Signal to replace a value
+        #
+        # @param value [Object] Replacement value
+        # @return [Result] A replace result
+        #
+        # @example Replace prompt
+        #   before_ask { |ctx| ctx.replace("Modified: #{ctx.prompt}") }
+        #
+        # @example Replace tool result
+        #   after_tool { |ctx| ctx.replace(sanitize(ctx.tool_result)) }
+        def replace(value)
+          Result.replace(value)
+        end
+      end
+    end
+  end
+end

data/lib/swarm_sdk/v3/hooks/result.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module V3
+    module Hooks
+      # Immutable value object representing the outcome of a hook execution
+      #
+      # A Result controls flow after a hook runs. Three actions are possible:
+      #
+      # - **continue** — proceed normally (default when hook returns nil or non-Result)
+      # - **halt** — stop processing; meaning varies by event:
+      #   - `before_ask`: returns nil from ask (same as interrupt)
+      #   - `before_tool`: returns error string to LLM without executing tool
+      # - **replace** — substitute a value:
+      #   - `before_ask`: replaces the prompt
+      #   - `after_tool`: replaces the tool result
+      #
+      # Results are created via factory methods, never directly instantiated
+      # by hook authors. Hook blocks return a Result to signal flow control.
+      #
+      # @example In a before_ask hook
+      #   before_ask { |ctx| ctx.halt("Not allowed") }
+      #
+      # @example In an after_tool hook
+      #   after_tool { |ctx| ctx.replace(sanitize(ctx.tool_result)) }
+      #
+      # @example Continue (explicit)
+      #   before_ask { |ctx| ctx.continue }
+      class Result
+        # Valid result actions
+        ACTIONS = [:continue, :halt, :replace].freeze
+
+        # @return [Symbol] The action (:continue, :halt, or :replace)
+        attr_reader :action
+
+        # @return [Object, nil] Associated value (halt message or replacement value)
+        attr_reader :value
+
+        class << self
+          # Create a continue result (proceed normally)
+          #
+          # @return [Result] A result with action :continue
+          #
+          # @example
+          #   Result.continue
+          def continue
+            new(action: :continue)
+          end
+
+          # Create a halt result (stop processing)
+          #
+          # @param message [String, nil] Optional halt message
+          # @return [Result] A result with action :halt
+          #
+          # @example With message
+          #   Result.halt("Bash disabled for this agent")
+          #
+          # @example Without message
+          #   Result.halt
+          def halt(message = nil)
+            new(action: :halt, value: message)
+          end
+
+          # Create a replace result (substitute a value)
+          #
+          # @param value [Object] Replacement value
+          # @return [Result] A result with action :replace
+          #
+          # @example Replace prompt
+          #   Result.replace("Modified prompt text")
+          #
+          # @example Replace tool result
+          #   Result.replace(sanitized_output)
+          def replace(value)
+            new(action: :replace, value: value)
+          end
+        end
+
+        # Whether this result signals to continue normally
+        #
+        # @return [Boolean]
+        def continue?
+          @action == :continue
+        end
+
+        # Whether this result signals to halt processing
+        #
+        # @return [Boolean]
+        def halt?
+          @action == :halt
+        end
+
+        # Whether this result signals to replace a value
+        #
+        # @return [Boolean]
+        def replace?
+          @action == :replace
+        end
+
+        private
+
+        # @param action [Symbol] One of ACTIONS
+        # @param value [Object, nil] Associated value
+        # @raise [ArgumentError] If action is not a valid action
+        def initialize(action:, value: nil)
+          raise ArgumentError, "Invalid action: #{action.inspect}. Must be one of: #{ACTIONS.join(", ")}" unless ACTIONS.include?(action)
+
+          @action = action
+          @value = value
+          freeze
+        end
+      end
+    end
+  end
+end

data/lib/swarm_sdk/v3/hooks/runner.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module V3
+    module Hooks
+      # Executes hooks for a given event in registration order
+      #
+      # Hooks are grouped by event type and executed sequentially. For tool events,
+      # hooks are filtered by their matcher before execution. The first hook that
+      # returns a non-continue {Result} short-circuits the chain.
+      #
+      # ## Match Parameter (tool hooks only)
+      #
+      # | Input       | Behavior                          |
+      # |-------------|-----------------------------------|
+      # | `nil`       | Matches all tools                 |
+      # | `:Bash`     | Exact match on tool name          |
+      # | `"Bash"`    | Exact match (same as Symbol)      |
+      # | `/pattern/` | Regex match (user controls anchor)|
+      # | `[:W, :E]`  | Exact match on any in the array   |
+      #
+      # @example
+      #   hooks = [
+      #     { event: :before_ask, block: ->(ctx) { puts ctx.prompt } },
+      #     { event: :before_tool, match: :Bash, block: ->(ctx) { ctx.halt("no bash") } },
+      #   ]
+      #   runner = Runner.new(hooks)
+      #   result = runner.run(:before_ask, context)
+      class Runner
+        # Supported hook events
+        EVENTS = [:before_ask, :after_ask, :before_tool, :after_tool, :on_stop].freeze
+
+        # Tool-specific event types (these support match filtering)
+        TOOL_EVENTS = [:before_tool, :after_tool].freeze
+
+        # Create a new runner from a list of hook configurations
+        #
+        # @param hooks [Array<Hash>] Hook config hashes with :event, :block, and optional :match
+        # @raise [KeyError] If a hook references an unknown event
+        #
+        # @example
+        #   Runner.new([
+        #     { event: :before_ask, block: my_proc },
+        #     { event: :before_tool, match: :Bash, block: guard_proc },
+        #   ])
+        def initialize(hooks = [])
+          @hooks = EVENTS.each_with_object({}) { |e, h| h[e] = [] }
+          hooks.each { |hook| @hooks.fetch(hook[:event]) << hook }
+        end
+
+        # Execute hooks for an event and return the controlling result
+        #
+        # Hooks run in registration order. The first hook that returns a
+        # non-continue {Result} wins and short-circuits the chain.
+        # If no hook returns a controlling result, {Result.continue} is returned.
+        #
+        # For tool events (:before_tool, :after_tool), hooks are filtered
+        # by their matcher against the context's tool_name.
+        #
+        # @param event [Symbol] Event type (one of EVENTS)
+        # @param context [Context] Hook context with event data
+        # @return [Result] The controlling result
+        #
+        # @example
+        #   result = runner.run(:before_ask, context)
+        #   if result.halt?
+        #     # stop processing
+        #   end
+        def run(event, context)
+          hooks_for_event = @hooks.fetch(event)
+          hooks_for_event = filter_by_matcher(hooks_for_event, context.tool_name) if tool_event?(event)
+
+          hooks_for_event.each do |hook|
+            result = hook[:block].call(context)
+            return result if result.is_a?(Result) && !result.continue?
+          end
+
+          Result.continue
+        end
+
+        # Whether any tool hooks are registered
+        #
+        # Used by Agent to skip around_tool_execution registration when
+        # no tool hooks exist, avoiding unnecessary overhead.
+        #
+        # @return [Boolean]
+        def any_tool_hooks?
+          @hooks[:before_tool].any? || @hooks[:after_tool].any?
+        end
+
+        private
+
+        # Whether the event is a tool-specific event
+        #
+        # @param event [Symbol] Event type
+        # @return [Boolean]
+        def tool_event?(event)
+          TOOL_EVENTS.include?(event)
+        end
+
+        # Filter hooks by their matcher against a tool name
+        #
+        # @param hooks [Array<Hash>] Hook configs to filter
+        # @param tool_name [String, nil] Tool name to match against
+        # @return [Array<Hash>] Matching hooks
+        def filter_by_matcher(hooks, tool_name)
+          hooks.select { |hook| matches?(hook[:match], tool_name) }
+        end
+
+        # Test whether a matcher matches a tool name
+        #
+        # @param matcher [nil, Symbol, String, Regexp, Array] Match specification
+        # @param tool_name [String, nil] Tool name to test
+        # @return [Boolean]
+        def matches?(matcher, tool_name)
+          case matcher
+          when nil then true
+          when Symbol then tool_name.to_s == matcher.to_s
+          when String then tool_name.to_s == matcher
+          when Regexp then matcher.match?(tool_name.to_s)
+          when Array then matcher.any? { |m| matches?(m, tool_name) }
+          else false
+          end
+        end
+      end
+    end
+  end
+end

data/lib/swarm_sdk/v3/mcp/connector.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module V3
+    module MCP
+      # Manages the full MCP client lifecycle
+      #
+      # Connects to an MCP server, discovers available tools, and provides
+      # methods to call tools and convert them to RubyLLM::Tool instances.
+      # Accepts an optional `transport:` for dependency injection in tests.
+      #
+      # @example Production usage
+      #   server = ServerDefinition.new(name: :api, type: :http, url: "http://localhost:3000/mcp")
+      #   connector = Connector.new(server)
+      #   connector.connect!
+      #   connector.available_tools  #=> [#<MCP::Client::Tool name="echo" ...>]
+      #   connector.call_tool("echo", message: "hello")
+      #   connector.disconnect!
+      #
+      # @example Test usage with injected transport
+      #   connector = Connector.new(server_def, transport: mock_transport)
+      #   connector.connect!
+      class Connector
+        # @return [ServerDefinition] Server configuration
+        attr_reader :server_definition
+
+        # @return [Array<MCP::Client::Tool>] Discovered MCP tools
+        attr_reader :available_tools
+
+        # Create a new connector
+        #
+        # @param server_definition [ServerDefinition] Server configuration
+        # @param transport [Object, nil] Optional transport for dependency injection.
+        #   Must respond to `send_request(request:)`. When nil, the transport
+        #   is built automatically from the server definition.
+        #
+        # @example
+        #   Connector.new(server_def)
+        #   Connector.new(server_def, transport: mock_transport)
+        def initialize(server_definition, transport: nil)
+          @server_definition = server_definition
+          @injected_transport = transport
+          @client = nil
+          @transport = nil
+          @available_tools = []
+        end
+
+        # Connect to the MCP server and discover tools
+        #
+        # Builds or uses the injected transport, creates an MCP::Client,
+        # and fetches the list of available tools from the server.
+        #
+        # @return [self] Returns self for chaining
+        # @raise [McpError] If the connection or tool discovery fails
+        #
+        # @example
+        #   connector.connect!
+        #   connector.available_tools.map(&:name) #=> ["echo", "read_file"]
+        def connect!
+          @transport = @injected_transport || build_transport
+          @client = ::MCP::Client.new(transport: @transport)
+          @available_tools = @client.tools
+          self
+        end
+
+        # Whether the connector is currently connected
+        #
+        # @return [Boolean]
+        def connected?
+          !@client.nil?
+        end
+
+        # Call an MCP tool by name
+        #
+        # @param name [String, Symbol] Tool name
+        # @param arguments [Hash] Tool arguments
+        # @return [String] Tool result content
+        # @raise [McpError] If the tool is not found
+        #
+        # @example
+        #   connector.call_tool("echo", message: "hello")
+        #   #=> "hello"
+        def call_tool(name, **arguments)
+          tool = @available_tools.find { |t| t.name == name.to_s }
+          raise McpError, "Unknown MCP tool: #{name}" unless tool
+
+          result = @client.call_tool(tool: tool, arguments: arguments)
+          extract_content(result)
+        end
+
+        # Convert MCP tools to RubyLLM::Tool instances
+        #
+        # Filters tools based on the server definition's tool list,
+        # then creates RubyLLM::Tool proxies for each.
+        #
+        # @return [Array<RubyLLM::Tool>] RubyLLM-compatible tool instances
+        #
+        # @example
+        #   tools = connector.to_ruby_llm_tools
+        #   chat.with_tools(*tools)
+        def to_ruby_llm_tools
+          tools_to_expose.map { |mcp_tool| ToolProxy.create(mcp_tool, self) }
+        end
+
+        # Disconnect from the MCP server
+        #
+        # Closes the transport and clears all state. Safe to call
+        # multiple times or when not connected.
+        #
+        # @return [void]
+        def disconnect!
+          @transport.close if @transport.respond_to?(:close)
+          @client = nil
+          @transport = nil
+          @available_tools = []
+        end
+
+        private
+
+        # Select tools to expose based on the server definition filter
+        #
+        # @return [Array<MCP::Client::Tool>] Filtered or all tools
+        def tools_to_expose
+          return @available_tools unless @server_definition.filter_tools?
+
+          allowed = @server_definition.tools.map(&:to_s)
+          @available_tools.select { |t| allowed.include?(t.name) }
+        end
+
+        # Build a transport from the server definition
+        #
+        # @return [StdioTransport, SslHttpTransport] Transport instance
+        def build_transport
+          case @server_definition.type
+          when :stdio
+            StdioTransport.new(
+              command: @server_definition.command,
+              args: @server_definition.args,
+              env: @server_definition.env,
+            )
+          when :http
+            SslHttpTransport.new(
+              url: @server_definition.url,
+              headers: @server_definition.headers.to_h,
+              ssl_verify: resolve_ssl_verify,
+            )
+          end
+        end
+
+        # Resolve effective SSL verification setting.
+        #
+        # Per-server ssl_verify takes precedence over the global config.
+        #
+        # @return [Boolean]
+        def resolve_ssl_verify
+          server_setting = @server_definition.ssl_verify
+          return server_setting unless server_setting.nil?
+
+          Configuration.instance.mcp_ssl_verify
+        end
+
+        # Extract text content from an MCP tool call result
+        #
+        # MCP tool results have the structure:
+        #   { "result" => { "content" => [{ "type" => "text", "text" => "..." }] } }
+        #
+        # @param result [Hash] Raw MCP tool call response
+        # @return [String] Extracted text content
+        def extract_content(result)
+          return result.to_s unless result.is_a?(Hash)
+
+          inner = result["result"]
+          return result.to_s unless inner.is_a?(Hash)
+
+          content = inner["content"]
+          return result.to_s unless content.is_a?(Array)
+
+          content.map { |c| c["text"] || c.to_s }.join("\n")
+        end
+      end
+    end
+  end
+end

data/lib/swarm_sdk/v3/mcp/mcp_error.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module V3
+    module MCP
+      # Error raised for MCP-related failures
+      #
+      # Covers connection errors, tool call failures, and transport issues.
+      #
+      # @example
+      #   raise McpError, "MCP server process exited unexpectedly"
+      class McpError < V3::Error; end
+    end
+  end
+end

data/lib/swarm_sdk/v3/mcp/server_definition.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module SwarmSDK
+  module V3
+    module MCP
+      # Immutable value object for MCP server configuration
+      #
+      # Supports two transport types:
+      # - `:stdio` — spawns a subprocess and communicates via JSON-RPC over stdin/stdout
+      # - `:http` — connects to an HTTP MCP endpoint
+      #
+      # @example Stdio server
+      #   ServerDefinition.new(
+      #     name: :filesystem,
+      #     type: :stdio,
+      #     command: "npx",
+      #     args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
+      #   )
+      #
+      # @example HTTP server with tool filtering
+      #   ServerDefinition.new(
+      #     name: :api,
+      #     type: :http,
+      #     url: "https://example.com/mcp",
+      #     headers: { "Authorization" => "Bearer token" },
+      #     tools: [:read_file, :list_directory],
+      #   )
+      class ServerDefinition
+        # @return [Symbol] Server identifier
+        attr_reader :name
+
+        # @return [Symbol] Transport type (:stdio or :http)
+        attr_reader :type
+
+        # @return [Array<Symbol>, nil] Tool names to expose (nil = all)
+        attr_reader :tools
+
+        # @return [String, nil] Subprocess command (stdio only)
+        attr_reader :command
+
+        # @return [Array<String>] Subprocess arguments (stdio only)
+        attr_reader :args
+
+        # @return [Hash<String, String>] Subprocess environment variables (stdio only)
+        attr_reader :env
+
+        # @return [String, nil] HTTP endpoint URL (http only)
+        attr_reader :url
+
+        # @return [Hash<String, String>] HTTP headers (http only)
+        attr_reader :headers
+
+        # @return [Boolean, nil] Per-server SSL verification override (nil = use global config)
+        attr_reader :ssl_verify
+
+        # Create a new server definition
+        #
+        # @param name [Symbol, String] Server identifier
+        # @param type [Symbol, String] Transport type (:stdio or :http)
+        # @param tools [Array<Symbol, String>, nil] Tool names to expose (nil = all)
+        # @param command [String, nil] Subprocess command (stdio)
+        # @param args [Array<String>] Subprocess arguments (stdio)
+        # @param env [Hash] Subprocess environment variables (stdio)
+        # @param url [String, nil] HTTP endpoint URL (http)
+        # @param headers [Hash] HTTP headers (http)
+        # @param ssl_verify [Boolean, nil] Override global SSL verification (nil = use global)
+        #
+        # @raise [ConfigurationError] If required fields are missing or type is invalid
+        #
+        # @example
+        #   ServerDefinition.new(name: :api, type: :http, url: "https://example.com/mcp")
+        #
+        # @example Disable SSL verification
+        #   ServerDefinition.new(name: :api, type: :http, url: "https://localhost/mcp", ssl_verify: false)
+        def initialize(name:, type:, tools: nil, **options)
+          @name = name.to_sym
+          @type = type.to_sym
+          @command = options[:command]
+          @args = Array(options[:args]).freeze
+          @env = (options[:env] || {}).transform_keys(&:to_s).freeze
+          @url = options[:url]
+          @headers = (options[:headers] || {}).freeze
+          @ssl_verify = options[:ssl_verify]
+          @tools = tools ? Array(tools).map(&:to_sym).freeze : nil
+
+          validate!
+          freeze
+        end
+
+        # Whether this definition filters exposed tools
+        #
+        # @return [Boolean] true if a specific tool list was provided
+        #
+        # @example
+        #   defn = ServerDefinition.new(name: :api, type: :http, url: "...", tools: [:echo])
+        #   defn.filter_tools? #=> true
+        #
+        #   defn = ServerDefinition.new(name: :api, type: :http, url: "...")
+        #   defn.filter_tools? #=> false
+        def filter_tools?
+          !@tools.nil?
+        end
+
+        private
+
+        # Validate configuration
+        #
+        # @raise [ConfigurationError] If validation fails
+        def validate!
+          unless [:stdio, :http].include?(@type)
+            raise ConfigurationError, "MCP server type must be :stdio or :http, got #{@type.inspect}"
+          end
+
+          if @type == :stdio && (@command.nil? || @command.to_s.strip.empty?)
+            raise ConfigurationError, "MCP stdio server requires a command"
+          end
+
+          if @type == :http && (@url.nil? || @url.to_s.strip.empty?)
+            raise ConfigurationError, "MCP http server requires a url"
+          end
+        end
+      end
+    end
+  end
+end