ruby-pi 0.1.8 → 0.1.10

data/lib/ruby_pi/tools/executor.rb

@@ -28,6 +28,35 @@ module RubyPi
     class Executor
       # Default timeout for each tool execution, in seconds.
       DEFAULT_TIMEOUT = 30
+      DEFAULT_MAX_CALLS = 32
+      DEFAULT_MAX_CONCURRENCY = 4
+      MAX_ACTIVE_EXECUTIONS = 16
+
+      @capacity_mutex = Mutex.new
+      @active_executions = 0
+
+      class << self
+        def active_execution_count
+          @capacity_mutex.synchronize { @active_executions }
+        end
+
+        private
+
+        def reserve_execution_capacity!
+          @capacity_mutex.synchronize do
+            if @active_executions >= MAX_ACTIVE_EXECUTIONS
+              raise RubyPi::ToolExecutionCapacityError,
+                    "Process already has #{MAX_ACTIVE_EXECUTIONS} active tool executions"
+            end
+
+            @active_executions += 1
+          end
+        end
+
+        def release_execution_capacity!
+          @capacity_mutex.synchronize { @active_executions -= 1 }
+        end
+      end
 
       # @return [Symbol] The execution mode (:parallel or :sequential).
       attr_reader :mode
@@ -35,20 +64,41 @@ module RubyPi
       # @return [Numeric] The per-tool timeout in seconds.
       attr_reader :timeout
 
+      # Recursively converts all string keys in a hash to symbols.
+      def self.deep_symbolize_keys(obj)
+        case obj
+        when Hash
+          obj.each_with_object({}) do |(key, value), result|
+            result[key.to_sym] = deep_symbolize_keys(value)
+          end
+        when Array
+          obj.map { |item| deep_symbolize_keys(item) }
+        else
+          obj
+        end
+      end
+
       # Creates a new Executor.
       #
       # @param registry [RubyPi::Tools::Registry] The registry to look up tools from.
       # @param mode [Symbol] Execution mode — :parallel or :sequential.
       # @param timeout [Numeric] Per-tool timeout in seconds (default: 30).
       # @raise [ArgumentError] If mode is not :parallel or :sequential.
-      def initialize(registry, mode: :parallel, timeout: DEFAULT_TIMEOUT)
+      def initialize(registry, mode: :parallel, timeout: DEFAULT_TIMEOUT,
+                     max_calls: DEFAULT_MAX_CALLS, max_concurrency: DEFAULT_MAX_CONCURRENCY)
         unless %i[parallel sequential].include?(mode)
           raise ArgumentError, "Mode must be :parallel or :sequential, got #{mode.inspect}"
         end
 
+        validate_positive_numeric!(:timeout, timeout)
+        validate_positive_integer!(:max_calls, max_calls)
+        validate_positive_integer!(:max_concurrency, max_concurrency)
+
         @registry = registry
         @mode = mode
         @timeout = timeout
+        @max_calls = max_calls
+        @max_concurrency = max_concurrency
       end
 
       # Executes a list of tool calls and returns their results.
@@ -64,6 +114,22 @@ module RubyPi
       # @return [Array<RubyPi::Tools::Result>] Results in the same order as the calls.
       # @raise [RubyPi::NoToolsRegisteredError] if registry is nil
       def execute(calls)
+        unless calls.is_a?(Array)
+          raise ArgumentError, "calls must be an Array, got #{calls.class}"
+        end
+
+        if calls.size > @max_calls
+          raise RubyPi::ToolCallLimitError,
+                "Model returned #{calls.size} tool calls; maximum is #{@max_calls} per execution"
+        end
+
+        return [] if calls.empty?
+
+        if Executor.active_execution_count >= MAX_ACTIVE_EXECUTIONS
+          raise RubyPi::ToolExecutionCapacityError,
+                "Refusing tool execution while #{MAX_ACTIVE_EXECUTIONS} tools are still running"
+        end
+
         # Issue #17: Guard against nil registry — if the LLM hallucinated tool
         # calls but no tools are registered, raise a typed error immediately
         # rather than crashing with NoMethodError on nil.find.
@@ -87,7 +153,24 @@ module RubyPi
       # @param calls [Array<Hash>] The tool call requests.
       # @return [Array<RubyPi::Tools::Result>] Ordered results.
       def execute_sequential(calls)
-        calls.map { |call| execute_single(call) }
+        results = []
+        calls.each_with_index do |call, index|
+          result = execute_single(call)
+          results << result
+          next unless result.completion_unknown?
+
+          calls.drop(index + 1).each do |skipped_call|
+            name = (skipped_call[:name] || skipped_call["name"]).to_s
+            results << Result.new(
+              name: name,
+              success: false,
+              status: :skipped,
+              error: "Tool '#{name}' was not started because a previous tool timed out with completion unknown"
+            )
+          end
+          break
+        end
+        results
       end
 
       # Executes tool calls in parallel using concurrent-ruby Futures.
@@ -108,9 +191,24 @@ module RubyPi
       # @param calls [Array<Hash>] The tool call requests.
       # @return [Array<RubyPi::Tools::Result>] Ordered results.
       def execute_parallel(calls)
+        return [] if calls.empty?
+
+        available_capacity = MAX_ACTIVE_EXECUTIONS - Executor.active_execution_count
+        pool_size = [@max_concurrency, calls.size, available_capacity].min
+        if pool_size <= 0
+          raise RubyPi::ToolExecutionCapacityError, "No safe capacity remains for parallel tool execution"
+        end
+
+        pool = Concurrent::FixedThreadPool.new(pool_size)
+        batch_started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
         futures = calls.map do |call|
-          Concurrent::Future.execute(executor: :io) do
-            execute_single(call)
+          Concurrent::Future.execute(executor: pool) do
+            Executor.send(:reserve_execution_capacity!)
+            begin
+              execute_direct(call)
+            ensure
+              Executor.send(:release_execution_capacity!)
+            end
           end
         end
 
@@ -124,7 +222,8 @@ module RubyPi
           # Issue #10: Wait for the future to complete, then check its state
           # explicitly. Future#value returns nil both on timeout AND when the
           # block legitimately returned nil, so we cannot use || to distinguish.
-          future.wait(@timeout)
+          elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - batch_started_at
+          future.wait([@timeout - elapsed, 0].max)
 
           if future.complete?
             if future.fulfilled?
@@ -157,11 +256,14 @@ module RubyPi
             Result.new(
               name: tool_name,
               success: false,
-              error: "Tool '#{tool_name}' timed out after #{@timeout}s",
+              status: :timeout_unknown,
+              error: "Tool '#{tool_name}' timed out after #{@timeout}s; completion and side effects are unknown",
               duration_ms: @timeout * 1000.0
             )
           end
         end
+      ensure
+        pool&.shutdown
       end
 
       # Executes a single tool call with error handling and timing.
@@ -179,44 +281,22 @@ module RubyPi
       # @return [RubyPi::Tools::Result] The execution result.
       def execute_single(call)
         tool_name = (call[:name] || call["name"]).to_s
-        arguments = deep_symbolize_keys(call[:arguments] || call["arguments"] || {})
-
-        tool = @registry.find(tool_name)
-
-        # Return an error result if the tool is not registered
-        unless tool
-          return Result.new(
-            name: tool_name,
-            success: false,
-            error: "Tool '#{tool_name}' not found in registry",
-            duration_ms: 0.0
-          )
-        end
-
-        # Execute the tool with a safe timeout mechanism.
-        # Instead of the stdlib timeout (which uses Thread#raise and is unsafe),
-        # we spawn a worker thread and join with a timeout.
         start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        worker_result = nil
 
-        # Container for the worker thread's result/error
-        value = nil
-        error = nil
-
-        worker = Thread.new do
-          # Don't spam stderr from the rescued worker thread.
-          Thread.current.report_on_exception = false
-          begin
-            value = tool.call(arguments)
-          rescue Exception => e # rubocop:disable Lint/RescueException
-            # Rescue the full Exception hierarchy (not just StandardError).
-            # If a tool block raises Interrupt, SystemExit, or any other
-            # non-StandardError, rescuing only StandardError leaves both
-            # `value` and `error` nil; the join then reports a successful
-            # nil result — a panic in a tool silently becomes "returned nil".
-            # Capture the failure here; the main thread surfaces it as a
-            # failed Result. The worker thread itself does not propagate.
-            error = e
+        Executor.send(:reserve_execution_capacity!)
+        begin
+          worker = Thread.new do
+            Thread.current.report_on_exception = false
+            begin
+              worker_result = execute_direct(call)
+            ensure
+              Executor.send(:release_execution_capacity!)
+            end
           end
+        rescue Exception # rubocop:disable Lint/RescueException
+          Executor.send(:release_execution_capacity!)
+          raise
         end
 
         # Join with timeout — returns nil if the thread didn't finish in time
@@ -231,24 +311,42 @@ module RubyPi
           Result.new(
             name: tool_name,
             success: false,
-            error: "Tool '#{tool_name}' timed out after #{@timeout}s",
-            duration_ms: elapsed_ms
-          )
-        elsif error
-          Result.new(
-            name: tool_name,
-            success: false,
-            error: "#{error.class}: #{error.message}",
+            status: :timeout_unknown,
+            error: "Tool '#{tool_name}' timed out after #{@timeout}s; completion and side effects are unknown",
             duration_ms: elapsed_ms
           )
         else
-          Result.new(
+          worker_result
+        end
+      end
+
+      # Executes a tool directly on the current thread. Parallel mode runs
+      # this method on a bounded pool; sequential mode wraps it in one worker
+      # solely to observe its deadline without asynchronously interrupting it.
+      def execute_direct(call)
+        tool_name = (call[:name] || call["name"]).to_s
+        arguments = deep_symbolize_keys(call[:arguments] || call["arguments"] || {})
+        tool = @registry.find(tool_name)
+
+        unless tool
+          return Result.new(
             name: tool_name,
-            success: true,
-            value: value,
-            duration_ms: elapsed_ms
+            success: false,
+            error: "Tool '#{tool_name}' not found in registry",
+            duration_ms: 0.0
           )
         end
+
+        start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        value = tool.call(arguments)
+        Result.new(name: tool_name, success: true, value: value, duration_ms: elapsed_since(start_time))
+      rescue Exception => e # rubocop:disable Lint/RescueException
+        Result.new(
+          name: tool_name,
+          success: false,
+          error: "#{e.class}: #{e.message}",
+          duration_ms: start_time ? elapsed_since(start_time) : 0.0
+        )
       end
 
       # Calculates milliseconds elapsed since a monotonic clock timestamp.
@@ -259,29 +357,6 @@ module RubyPi
         (Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time) * 1000.0
       end
 
-      # Recursively converts all string keys in a hash to symbols so that
-      # tool implementations can use idiomatic Ruby symbol-key access
-      # (e.g. `args[:field]`) regardless of whether the LLM provider
-      # returned string-keyed JSON. Exposed as a class method so the agent
-      # loop can apply the same transformation to tool_call arguments
-      # before recording them in `tool_calls_made`, keeping the agent's
-      # observable arguments shape consistent with what tool blocks see.
-      #
-      # @param obj [Object] the object to transform (Hash, Array, or scalar)
-      # @return [Object] the transformed object with symbolized keys
-      def self.deep_symbolize_keys(obj)
-        case obj
-        when Hash
-          obj.each_with_object({}) do |(key, value), result|
-            result[key.to_sym] = deep_symbolize_keys(value)
-          end
-        when Array
-          obj.map { |item| deep_symbolize_keys(item) }
-        else
-          obj
-        end
-      end
-
       # Instance-method delegate so existing internal callers keep working.
       #
       # @param obj [Object] the object to transform (Hash, Array, or scalar)
@@ -289,6 +364,17 @@ module RubyPi
       def deep_symbolize_keys(obj)
         self.class.deep_symbolize_keys(obj)
       end
+
+      def validate_positive_numeric!(name, value)
+        valid = value.is_a?(Numeric) && !value.is_a?(Complex) && value.finite? && value.positive?
+        raise ArgumentError, "#{name} must be a finite positive number, got #{value.inspect}" unless valid
+      end
+
+      def validate_positive_integer!(name, value)
+        return if value.is_a?(Integer) && value.positive?
+
+        raise ArgumentError, "#{name} must be a positive integer, got #{value.inspect}"
+      end
     end
   end
 end

data/lib/ruby_pi/tools/result.rb

@@ -36,6 +36,9 @@ module RubyPi
       # @return [Float] The execution time in milliseconds.
       attr_reader :duration_ms
 
+      # @return [Symbol] :success, :error, :timeout_unknown, or :skipped
+      attr_reader :status
+
       # Creates a new Result instance.
       #
       # @param name [String, Symbol] The name of the tool that produced this result.
@@ -43,12 +46,13 @@ module RubyPi
       # @param value [Object, nil] The return value from the tool (on success).
       # @param error [String, nil] The error message (on failure).
       # @param duration_ms [Float] How long the tool took to execute, in milliseconds.
-      def initialize(name:, success:, value: nil, error: nil, duration_ms: 0.0)
+      def initialize(name:, success:, value: nil, error: nil, duration_ms: 0.0, status: nil)
         @name = name.to_s
         @success = success
         @value = value
         @error = error
         @duration_ms = duration_ms.to_f
+        @status = status || (success ? :success : :error)
       end
 
       # Returns whether the tool execution was successful.
@@ -58,6 +62,16 @@ module RubyPi
         @success
       end
 
+      # A timeout cannot prove that side effects did not commit. This predicate
+      # makes that uncertainty explicit to callers.
+      def completion_unknown?
+        @status == :timeout_unknown
+      end
+
+      def skipped?
+        @status == :skipped
+      end
+
       # Returns a hash representation of the result, useful for serialization.
       #
       # @return [Hash] A hash containing all result attributes.
@@ -67,7 +81,8 @@ module RubyPi
           success: @success,
           value: @value,
           error: @error,
-          duration_ms: @duration_ms
+          duration_ms: @duration_ms,
+          status: @status
         }
       end
 

data/lib/ruby_pi/version.rb

@@ -7,5 +7,5 @@
 
 module RubyPi
   # The current version of the RubyPi gem, following Semantic Versioning.
-  VERSION = "0.1.8"
+  VERSION = "0.1.10"
 end

data/lib/ruby_pi.rb

@@ -21,6 +21,7 @@ require_relative "ruby_pi/errors"
 require_relative "ruby_pi/llm/response"
 require_relative "ruby_pi/llm/tool_call"
 require_relative "ruby_pi/llm/stream_event"
+require_relative "ruby_pi/llm/sse_parser"
 require_relative "ruby_pi/llm/model"
 require_relative "ruby_pi/llm/base_provider"
 require_relative "ruby_pi/llm/gemini"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby-pi
 version: !ruby/object:Gem::Version
-  version: 0.1.8
+  version: 0.1.10
 platform: ruby
 authors:
 - RubyPi Contributors
@@ -141,6 +141,7 @@ files:
 - lib/ruby_pi/llm/model.rb
 - lib/ruby_pi/llm/openai.rb
 - lib/ruby_pi/llm/response.rb
+- lib/ruby_pi/llm/sse_parser.rb
 - lib/ruby_pi/llm/stream_event.rb
 - lib/ruby_pi/llm/tool_call.rb
 - lib/ruby_pi/tools/definition.rb
@@ -171,7 +172,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 4.0.15
 specification_version: 4
 summary: AI agent harness for Ruby — build LLM agents with tool calling, streaming,
   and a unified interface to OpenAI, Anthropic Claude, and Google Gemini.