rspec-agents 0.1.0

data/lib/async_workers/transport/unix_socket_transport.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require "socket"
+require "open3"
+require_relative "base"
+require_relative "../errors"
+
+module AsyncWorkers
+  module Transport
+    # Transport over Unix domain socket using socketpair.
+    # RPC messages go over the socket.
+    # Both stdout and stderr are available for log capture.
+    class UnixSocketTransport < Base
+      attr_reader :wait_thread
+
+      # @param command [Array<String>] Command to execute
+      # @param env [Hash] Environment variables
+      # @param chdir [String, nil] Working directory for the process
+      def initialize(command:, env: {}, chdir: nil)
+        @command       = command
+        @env           = env
+        @chdir         = chdir
+        @closed        = false
+        @parent_socket = nil
+        @child_socket  = nil
+        @stdout        = nil
+        @stderr        = nil
+        @wait_thread   = nil
+      end
+
+      # Spawn the process with socket pair for RPC.
+      # Child receives RPC_SOCKET_FD environment variable.
+      # @return [Integer] PID
+      def spawn
+        # Create socket pair - parent and child ends
+        @parent_socket, @child_socket = Socket.pair(:UNIX, :STREAM, 0)
+
+        child_fd = @child_socket.fileno
+
+        # Prepare environment with socket fd
+        spawn_env = @env.merge("RPC_SOCKET_FD" => child_fd.to_s)
+
+        # Use Open3.popen3 with extra spawn options to inherit the socket fd
+        spawn_opts = { child_fd => child_fd, close_others: false }
+        spawn_opts[:chdir] = @chdir if @chdir
+
+        stdin, @stdout, @stderr, @wait_thread = Open3.popen3(
+          spawn_env,
+          *@command,
+          **spawn_opts
+        )
+
+        # Close stdin since we use socket for RPC
+        stdin.close
+        # Close child end of socket in parent
+        @child_socket.close
+
+        @parent_socket.sync = true
+        @stdout.sync = true
+        @stderr.sync = true
+
+        @wait_thread.pid
+      end
+
+      def write_line(line)
+        raise ChannelClosedError, "Transport closed" if @closed
+        @parent_socket.puts(line)
+        @parent_socket.flush
+      end
+
+      def read_line
+        return nil if @closed
+        line = @parent_socket.gets
+        return nil if line.nil?
+        line.chomp
+      end
+
+      # @return [IO] stdout stream (available for logs in socket mode)
+      def stdout_reader
+        @stdout
+      end
+
+      def stderr_reader
+        @stderr
+      end
+
+      def close
+        return if @closed
+        @closed = true
+
+        @parent_socket&.close rescue nil
+        @stdout&.close rescue nil
+        @stderr&.close rescue nil
+      end
+
+      def closed?
+        @closed
+      end
+
+      def pid
+        @wait_thread&.pid
+      end
+
+      # Wait for the process to exit and return exit status.
+      # Uses Open3's wait_thread which handles process reaping.
+      # @return [Process::Status]
+      def wait_for_exit
+        @wait_thread&.value
+      end
+    end
+  end
+end

data/lib/async_workers/worker_group.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+require "async"
+require_relative "errors"
+require_relative "channel_config"
+require_relative "managed_process"
+
+module AsyncWorkers
+  # Coordinates multiple identical workers in a fan-out pattern.
+  # Provides fail-fast semantics: if any worker exits with non-zero status,
+  # all other workers are killed immediately.
+  #
+  # @example Fan-out work to multiple workers
+  #   Async do |task|
+  #     group = WorkerGroup.new(
+  #       size: 4,
+  #       command: ['ruby', 'worker.rb'],
+  #       rpc: ChannelConfig.stdio_rpc
+  #     )
+  #
+  #     group.start(task: task)
+  #
+  #     # Set up handlers
+  #     group.each_with_index do |worker, i|
+  #       worker.stderr.on_data { |line| puts "[worker-#{i}] #{line}" }
+  #     end
+  #
+  #     # Fan-out work
+  #     results = group.map do |worker|
+  #       worker.rpc.request({ action: 'process', data: '...' })
+  #     end
+  #
+  #     group.stop
+  #   end
+  #
+  class WorkerGroup
+    include Enumerable
+
+    # @return [Array<ManagedProcess>] All workers
+    attr_reader :workers
+    alias_method :to_a, :workers
+
+    # @return [Integer] Number of workers
+    attr_reader :size
+
+    # @return [WorkerFailure, nil] First failure encountered
+    attr_reader :failure
+
+    # @param size [Integer] Number of workers to spawn
+    # @param command [Array<String>] Command to execute for each worker
+    # @param env [Hash] Base environment variables (WORKER_INDEX added automatically)
+    # @param rpc [ChannelConfig] RPC configuration
+    def initialize(size:, command:, env: {}, rpc: ChannelConfig.no_rpc)
+      @size              = size
+      @command           = command
+      @base_env          = env
+      @rpc_config        = rpc
+      @stopping          = false
+      @failure           = nil
+      @failure_condition = nil
+      @failure_mutex     = Mutex.new
+
+      @workers = size.times.map do |i|
+        ManagedProcess.new(
+          command: command,
+          env:     env.merge("WORKER_INDEX" => i.to_s),
+          rpc:     rpc
+        )
+      end
+    end
+
+    # Spawn all workers.
+    # @param task [Async::Task] Parent async task
+    def start(task:)
+      @failure_condition = Async::Condition.new
+
+      @workers.each_with_index do |worker, i|
+        worker.on_exit do |status|
+          handle_worker_exit(i, status) unless @stopping
+        end
+        worker.start(task: task)
+      end
+    end
+
+    # Access worker by index.
+    # @param index [Integer] Worker index
+    # @return [ManagedProcess]
+    def [](index)
+      @workers[index]
+    end
+
+    # Iterate over workers.
+    # @yield [ManagedProcess] Each worker
+    def each(&block)
+      @workers.each(&block)
+    end
+
+    # Graceful shutdown of all workers (parallel).
+    # @param timeout [Numeric] Timeout per worker
+    def stop(timeout: 5)
+      @stopping = true
+
+      # Stop all workers - if we're in an Async context, run in parallel
+      if Async::Task.current?
+        tasks = @workers.map do |worker|
+          Async::Task.current.async { worker.stop(timeout: timeout) }
+        end
+        tasks.each(&:wait)
+      else
+        # Not in async context, stop sequentially
+        @workers.each { |worker| worker.stop(timeout: timeout) }
+      end
+    end
+
+    # Immediate kill of all workers.
+    def kill
+      @stopping = true
+      @workers.each(&:kill)
+    end
+
+    # Block until all workers exit.
+    # @param timeout [Numeric, nil] Optional timeout in seconds
+    # @return [Array<Process::Status>] Exit statuses of all workers
+    # @raise [Async::TimeoutError] If timeout exceeded
+    def wait(timeout: nil)
+      if timeout
+        Async::Task.current.with_timeout(timeout) do
+          @workers.map(&:wait)
+        end
+      else
+        @workers.map(&:wait)
+      end
+    end
+
+    # Check if all workers are running.
+    # @return [Boolean]
+    def alive?
+      @workers.all?(&:alive?)
+    end
+
+    # Check if any worker has failed.
+    # @return [Boolean]
+    def failed?
+      !@failure.nil?
+    end
+
+    # Block until a worker fails.
+    # @return [WorkerFailure] The failure exception
+    def wait_for_failure
+      @failure_condition.wait
+    end
+
+    private
+
+    def handle_worker_exit(index, status)
+      return if status.nil? || status.success?
+
+      # Use mutex to ensure only first failure is recorded
+      first_failure = @failure_mutex.synchronize do
+        return if @failure # Already handling a failure
+        @failure = WorkerFailure.new(worker_index: index, exit_status: status)
+      end
+
+      return unless first_failure
+
+      @failure_condition.signal(@failure)
+
+      # Kill all other workers
+      @stopping = true
+      @workers.each_with_index do |worker, i|
+        worker.kill if i != index && worker.alive?
+      end
+    end
+  end
+end

data/lib/async_workers.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "async"
+
+require_relative "async_workers/errors"
+require_relative "async_workers/channel_config"
+require_relative "async_workers/output_stream"
+require_relative "async_workers/transport/base"
+require_relative "async_workers/transport/stdio_transport"
+require_relative "async_workers/transport/unix_socket_transport"
+require_relative "async_workers/rpc_channel"
+require_relative "async_workers/managed_process"
+require_relative "async_workers/worker_group"
+
+module AsyncWorkers
+  VERSION = "0.1.0"
+end

data/lib/rspec/agents/agent_response.rb

@@ -0,0 +1,61 @@
+module RSpec
+  module Agents
+    # Represents a response from the agent under test
+    class AgentResponse
+      attr_reader :text, :tool_calls, :metadata
+
+      # @param text [String] The agent's response text
+      # @param tool_calls [Array<ToolCall>] Tool calls made during this response
+      # @param metadata [Metadata] Optional provider-specific data
+      def initialize(text:, tool_calls: [], metadata: Metadata.new)
+        @text = text
+        @tool_calls = tool_calls
+        @metadata = metadata
+      end
+
+      def has_tool_call?(name, params: nil)
+        @tool_calls.any? do |tc|
+          tc.name == name.to_sym && tc.matches_params?(params)
+        end
+      end
+
+      def find_tool_calls(name, params: nil)
+        @tool_calls.select do |tc|
+          tc.name == name.to_sym && tc.matches_params?(params)
+        end
+      end
+
+      def tool_call(name)
+        @tool_calls.find { |tc| tc.name == name.to_sym }
+      end
+
+      def empty?
+        @text.nil? || @text.empty?
+      end
+
+      def length
+        @text&.length || 0
+      end
+
+      def match?(pattern)
+        pattern.match?(@text.to_s)
+      end
+
+      def include?(substring)
+        @text.to_s.include?(substring)
+      end
+
+      def to_h
+        {
+          text:       @text,
+          tool_calls: @tool_calls.map(&:to_h),
+          metadata:   @metadata.to_h
+        }
+      end
+
+      def to_s
+        @text.to_s
+      end
+    end
+  end
+end

data/lib/rspec/agents/agents/base.rb

@@ -0,0 +1,123 @@
+module RSpec
+  module Agents
+    module Agents
+      # Base class for agent adapters
+      # Agent adapters handle communication with the chatbot being tested
+      #
+      # Each test execution receives a fresh agent instance, allowing per-test
+      # configuration and state isolation.
+      #
+      # @example Implementing a custom agent
+      #   class MyHttpAgent < RSpec::Agents::Agents::Base
+      #     def self.build(context = {})
+      #       new(
+      #         base_url: ENV["AGENT_URL"],
+      #         api_key: ENV["AGENT_API_KEY"],
+      #         context: context
+      #       )
+      #     end
+      #
+      #     def initialize(base_url:, api_key:, context: {})
+      #       super(context: context)
+      #       @base_url = base_url
+      #       @api_key = api_key
+      #     end
+      #
+      #     def chat(messages, on_tool_call: nil)
+      #       response = HTTParty.post("#{@base_url}/chat", ...)
+      #       tool_calls = parse_tool_calls(response["tool_calls"])
+      #
+      #       # Signal each tool call via callback if provided
+      #       tool_calls.each { |tc| on_tool_call&.call(tc) }
+      #
+      #       AgentResponse.new(
+      #         text: response["content"],
+      #         tool_calls: tool_calls,
+      #         metadata: { latency_ms: elapsed }
+      #       )
+      #     end
+      #   end
+      class Base
+        # Factory method called by the framework for each test
+        # Override this in subclasses to customize instantiation
+        #
+        # @param context [Hash] Test execution context containing:
+        #   - :test_name [String] Full RSpec example description
+        #   - :test_file [String] Source file path
+        #   - :test_line [Integer] Line number of the test
+        #   - :tags [Hash] RSpec metadata tags (:focus, :slow, etc.)
+        #   - :scenario [String] Scenario name if using external scenario files
+        # @return [Base] Agent instance
+        def self.build(context = {})
+          new(context: context)
+        end
+
+        # @param context [Hash] Test execution context
+        def initialize(context: {})
+          @context = context
+        end
+
+        # Send messages and receive a response
+        # This is the main method that subclasses must implement
+        #
+        # @param messages [Array<Hash, Message>] Conversation history
+        #   Each message has :role ("user" or "agent") and :content
+        # @param on_tool_call [Proc, nil] Optional callback invoked for each tool call
+        #   Callback receives a ToolCall object as argument
+        # @return [AgentResponse] The agent's response
+        def chat(messages, on_tool_call: nil)
+          raise NotImplementedError, "#{self.class} must implement #chat(messages, on_tool_call: nil)"
+        end
+
+        # Reset conversation state (for stateful agents)
+        # Override in subclasses that maintain internal state
+        def reset!
+          # Default no-op
+        end
+
+        # Wrap test execution for isolation (e.g., database transactions)
+        # Override in subclasses to provide custom wrapping behavior
+        #
+        # @yield The test block to execute
+        # @return [Object] The result of the block
+        #
+        # @example Wrapping in a database transaction
+        #   def around(&block)
+        #     ActiveRecord::Base.transaction(requires_new: true) do
+        #       block.call
+        #       raise ActiveRecord::Rollback
+        #     end
+        #   end
+        def around(&block)
+          block.call  # Default: no-op wrapping
+        end
+
+        # Agent metadata for reporting
+        # Override to provide useful debugging information
+        #
+        # @return [Metadata]
+        def metadata
+          Metadata.new
+        end
+
+        protected
+
+        attr_reader :context
+
+        # Helper to convert messages to a standard format
+        # @param messages [Array] Messages in various formats
+        # @return [Array<Hash>] Normalized messages
+        def normalize_messages(messages)
+          messages.map do |msg|
+            case msg
+            when Hash
+              { role: msg[:role] || msg["role"], content: msg[:content] || msg["content"] }
+            else
+              { role: msg.role, content: msg.content }
+            end
+          end
+        end
+      end
+    end
+  end
+end