phronomy 0.13.0 → 0.15.0

data/lib/phronomy/llm_adapter/base.rb

@@ -4,7 +4,11 @@ module Phronomy
   module LLMAdapter
     # Abstract base class for LLM adapters.
     #
-    # Subclasses must implement {#complete} and {#stream}.
+    # Subclasses must implement {#complete} and {#stream}. The adapter or the
+    # underlying provider client owns transport timeout, retry, backoff, and
+    # rate-limit behavior. Phronomy only supplies cooperative cancellation and
+    # isolates blocking calls in {BlockingAdapterPool}.
+    #
     # The agent pipeline calls {#complete_async} / {#stream_async} which wrap
     # those methods in a {BlockingAdapterPool} submission.
     class Base
@@ -14,7 +18,7 @@ module Phronomy
       #
       # @param chat    [Object] the configured chat session object
       # @param message [String] the user message
-      # @param config  [Hash]  the invocation config (e.g. +:cancellation_token+)
+      # @param config  [Hash] invocation config (e.g. +:cancellation_token+)
       # @return [Object] LLM response object
       # @raise [NotImplementedError]
       # @api private
@@ -28,7 +32,7 @@ module Phronomy
       #
       # @param chat    [Object] the configured chat session object
       # @param message [String] the user message
-      # @param config  [Hash]  the invocation config
+      # @param config  [Hash] invocation config
       # @yield [chunk] streaming chunk from the LLM
       # @return [Object] LLM response object
       # @raise [NotImplementedError]
@@ -40,16 +44,18 @@ module Phronomy
       # Submits a non-streaming LLM call to {BlockingAdapterPool} and returns
       # a {BlockingAdapterPool::PendingOperation}.
       #
+      # Transport timeout and retry remain the responsibility of the adapter or
+      # provider client; Phronomy does not attach an additional operation timeout.
+      #
       # @param chat    [Object] configured chat session
       # @param message [String] user message
-      # @param config  [Hash]  invocation config
+      # @param config  [Hash] invocation config
       # @param pool    [BlockingAdapterPool] pool to submit to
       # @return [BlockingAdapterPool::PendingOperation]
       # @api private
       def complete_async(chat, message, config: {}, pool: default_pool)
         token = config[:cancellation_token]
-        timeout = config[:llm_timeout]
-        pool.submit(timeout: timeout, cancellation_token: token) do
+        pool.submit(cancellation_token: token) do
           complete(chat, message, config: config)
         end
       end
@@ -57,39 +63,24 @@ module Phronomy
       # Submits a streaming LLM call to {BlockingAdapterPool} and returns
       # a {BlockingAdapterPool::PendingOperation}.
       #
-      # When +enqueue_to:+ is given, streaming chunks are pushed into that
-      # {AsyncQueue} from the worker thread instead of being passed directly
-      # to the caller's block.  The queue is closed (via +ensure+) after the
-      # LLM call finishes so the consumer's drain loop terminates naturally.
-      # This keeps user-supplied blocks off the blocking-pool worker thread.
+      # The block is invoked on the blocking-pool worker thread. Agent code must
+      # pass only a lightweight internal sink that posts a value to EventLoop;
+      # Application callbacks must never be passed directly to this method.
       #
-      # When +enqueue_to:+ is nil and a block is given, the block is invoked
-      # directly from the worker thread (legacy behaviour, preserved for
-      # backward compatibility).
+      # Transport timeout and retry remain the responsibility of the adapter or
+      # provider client; Phronomy does not attach an additional operation timeout.
       #
-      # @param chat       [Object] configured chat session
-      # @param message    [String] user message
-      # @param config     [Hash]   invocation config
-      # @param pool       [BlockingAdapterPool] pool to submit to
-      # @param enqueue_to [AsyncQueue, nil] when set, push chunks here instead of
-      #   calling the block on the worker thread
-      # @yield [chunk] streaming chunk — only used when +enqueue_to:+ is nil
+      # @yield [chunk] streaming chunk on the worker thread
       # @return [BlockingAdapterPool::PendingOperation]
       # @api private
-      def stream_async(chat, message, config: {}, pool: default_pool, enqueue_to: nil, &block)
+      def stream_async(chat, message, config: {}, pool: default_pool, &block)
+        raise ArgumentError, "stream_async requires a block" unless block
+
         token = config[:cancellation_token]
-        timeout = config[:llm_timeout]
-        if enqueue_to
-          pool.submit(timeout: timeout, cancellation_token: token) do
-            stream(chat, message, config: config) do |chunk|
-              enqueue_to.push(chunk)
-            end
-          ensure
-            enqueue_to.close
-          end
-        else
-          pool.submit(timeout: timeout, cancellation_token: token) do
-            stream(chat, message, config: config, &block)
+        pool.submit(cancellation_token: token) do
+          stream(chat, message, config: config) do |chunk|
+            token&.raise_if_cancelled!("invocation cancelled during streaming")
+            block.call(chunk)
           end
         end
       end

data/lib/phronomy/metrics.rb

@@ -20,15 +20,18 @@ module Phronomy
     # @return [Hash{Symbol => Numeric}]
     # @api public
     def self.snapshot
-      pool = Runtime.instance.blocking_io
-      el = EventLoop.instance
-      task_snap = Runtime.instance.task_snapshot
+      runtime = Runtime.instance
+      pool = runtime.blocking_io
+      el = runtime.event_loop
+      task_snap = runtime.task_snapshot
 
       {
         blocking_pool_active: pool.active_count,
         blocking_pool_queue_length: pool.queue_depth,
         blocking_pool_abandoned_total: pool.abandoned_count,
         blocking_pool_size: pool.pool_size,
+        event_loop_queue_depth: el.queue_depth,
+        event_loop_queue_max_depth: el.max_queue_depth,
         event_loop_lag_last_ms: (el.last_lag_seconds * 1000).round(3),
         event_loop_lag_max_ms: (el.max_lag_seconds * 1000).round(3),
         event_loop_lag_average_ms: (el.average_lag_seconds * 1000).round(3)

data/lib/phronomy/multi_agent/parallel_tool_chat.rb

@@ -2,122 +2,90 @@
 
 module Phronomy
   module MultiAgent
-    # RubyLLM::Chat subclass that executes multiple tool calls concurrently.
+    # RubyLLM::Chat subclass supporting concurrent direct Tool execution.
     #
-    # When the LLM returns more than one tool call in a single response, each
-    # tool is dispatched according to its +execution_mode+:
-    # - +:cooperative+ tools run via +Runtime.instance.spawn+, delegating
-    #   scheduling to the configured runtime backend.
-    # - +:blocking_io+ tools are offloaded to a +BlockingAdapterPool+ worker
-    #   thread so they do not occupy a scheduler task slot.
-    # All results are collected before being appended to the message history,
-    # preserving deterministic message order while reducing wall-clock latency
-    # when tools are IO-bound (HTTP calls, DB queries, etc.).
-    #
-    # Single-tool responses fall through to the standard sequential path via
-    # +super+, preserving all existing edge-case behaviour (Tool::Halt,
-    # forced_tool_choice, streaming, SuspendSignal, etc.).
-    #
-    # This class is used automatically when EventLoop mode is enabled
-    # ({Phronomy.configuration.event_loop}).  It is not used for direct
-    # synchronous +invoke+ calls so that the streaming callback state remains
-    # single-threaded.
+    # AgentInvocation installs +on_tool_call_batch+ and intercepts the whole batch
+    # before this class dispatches anything. The direct-chat fallback dispatches
+    # the complete batch concurrently; process protection remains the responsibility
+    # of Runtime's bounded executors and queues.
     # @api private
     class ParallelToolChat < RubyLLM::Chat
-      # @param max_parallel_tools [Integer] maximum simultaneous tool executions
-      # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil] token observed before each batch
-      # @param opts [Hash] remaining kwargs forwarded to RubyLLM::Chat
-      # @api private
-      def initialize(max_parallel_tools: 10, cancellation_token: nil, **opts)
+      def initialize(cancellation_token: nil, **opts)
         super(**opts)
-        @max_parallel_tools = max_parallel_tools
         @cancellation_token = cancellation_token
       end
 
-      # Allows the owning agent to update the token between retries.
-      # @api private
       attr_writer :cancellation_token
 
+      # Registers an Agent-owned batch interceptor. The callback must return
+      # quickly or raise ToolCallIntercepted; it must not execute Tool bodies.
+      def on_tool_call_batch(&block)
+        @on[:tool_call_batch] = block
+        self
+      end
+
       private
 
-      # Overrides RubyLLM::Chat#handle_tool_calls to parallelise execution
-      # when multiple tool calls are present in a single LLM response.
-      #
-      # The method preserves the three-phase protocol of the original:
-      #   1. Pre-execution callbacks (+on_new_message+, +on_tool_call+) —
-      #      sequential so that the Suspendable concern's approval hook can
-      #      raise +SuspendSignal+ before any tool is executed.
-      #   2. Parallel tool execution — cooperative tools via Runtime.instance.spawn
-      #      (respects the configured runtime backend), blocking_io tools via BlockingAdapterPool.
-      #   3. Post-execution callbacks and message recording — sequential,
-      #      in the original tool-call order.
-      #
-      # @param response [RubyLLM::Message] the LLM response containing tool calls
-      # @yield streaming block forwarded to +complete+
-      # @api private
       def handle_tool_calls(response, &block)
         tool_calls = response.tool_calls.values
-
-        # Single tool: delegate to the parent implementation to preserve every
-        # edge case (forced_tool_choice, streaming, Halt, SuspendSignal…).
         return super if tool_calls.size <= 1
 
-        # Phase 1 — pre-execution callbacks (sequential, original order).
-        # The SuspendSignal approval hook is registered via on_tool_call, so it
-        # MUST fire before execution begins.
+        if @on[:tool_call_batch]
+          tool_calls.each { @on[:new_message]&.call }
+          @on[:tool_call_batch].call(tool_calls)
+          return
+        end
+
+        # Direct ParallelToolChat fallback. Agent execution never reaches this
+        # branch because AgentInvocation installs the batch interceptor first.
         tool_calls.each do |tool_call|
           @on[:new_message]&.call
           @on[:tool_call]&.call(tool_call)
         end
 
-        # Phase 2 — parallel tool execution.
-        # :cooperative tools run inside a Task (no pool).
-        # :blocking_io/:cpu_bound/:external_process tools are submitted directly
-        # to BlockingAdapterPool when available — eliminating the extra Task
-        # Thread that previously wrapped each pool operation.
-        #
-        # Both Phronomy::Task and BlockingAdapterPool::PendingOperation support
-        # #wait_result, so results are collected uniformly below.
-        ct = @cancellation_token
-        max = @max_parallel_tools
-        tool_results = tool_calls.each_slice(max).flat_map do |batch|
-          if ct&.cancelled?
-            raise Phronomy::CancellationError, "invocation cancelled before tool execution"
-          end
-
-          # Dispatch all tools in this batch via ToolExecutor (centralised routing).
-          dispatched = batch.map do |tc|
-            tool = tools[tc.name.to_sym]
-            unless tool
-              next {tool_call: tc, awaitable: nil, result: {
-                error: "Model tried to call unavailable tool `#{tc.name}`. " \
-                       "Available tools: #{tools.keys.to_json}."
-              }}
-            end
+        cancellation_token = @cancellation_token
+        if cancellation_token&.cancelled?
+          raise Phronomy::CancellationError,
+            "invocation cancelled before tool execution"
+        end
 
-            awaitable = Phronomy::Agent::ToolExecutor.call_async(
-              tool: tool,
-              args: tc.arguments,
-              cancellation_token: ct
-            )
-            {tool_call: tc, awaitable: awaitable, result: nil}
+        dispatched = tool_calls.map do |tool_call|
+          tool = tools[tool_call.name.to_sym]
+          unless tool
+            next {
+              tool_call: tool_call,
+              awaitable: nil,
+              result: {
+                error: "Model tried to call unavailable tool `#{tool_call.name}`. " \
+                  "Available tools: #{tools.keys.to_json}."
+              }
+            }
           end
 
-          # Await all dispatched operations in original order.
-          dispatched.map do |item|
-            result = item[:awaitable] ? item[:awaitable].wait_result : item[:result]
-            {tool_call: item[:tool_call], result: result}
-          end
+          awaitable = Phronomy::Agent::ToolExecutor.call_async(
+            tool: tool,
+            args: tool_call.arguments,
+            cancellation_token: cancellation_token
+          )
+          {tool_call: tool_call, awaitable: awaitable, result: nil}
+        end
+
+        tool_results = dispatched.map do |item|
+          result = item[:awaitable] ? item[:awaitable].wait_result : item[:result]
+          {tool_call: item[:tool_call], result: result}
         end
 
-        # Phase 3 — post-execution callbacks and message recording (sequential).
         halt_result = nil
         tool_results.each do |item|
           result = item[:result]
           @on[:tool_result]&.call(result)
           tool_payload = result.is_a?(RubyLLM::Tool::Halt) ? result.content : result
           content = content_like?(tool_payload) ? tool_payload : tool_payload.to_s
-          message = add_message(role: :tool, content: content, tool_call_id: item[:tool_call].id)
+          message = add_message(
+            role: :tool,
+            content: content,
+            tool_call_id: item[:tool_call].id
+          )
           @on[:end_message]&.call(message)
           halt_result = result if result.is_a?(RubyLLM::Tool::Halt)
         end
@@ -126,15 +94,12 @@ module Phronomy
         halt_result || complete(&block)
       end
 
-      # Overrides RubyLLM::Chat#execute_tool to forward the cancellation token
-      # explicitly and to route the call through {ToolExecutor} so that the
-      # execution_mode decision is made in a single place.
       def execute_tool(tool_call)
         tool = tools[tool_call.name.to_sym]
         unless tool
           return {
             error: "Model tried to call unavailable tool `#{tool_call.name}`. " \
-                   "Available tools: #{tools.keys.to_json}."
+              "Available tools: #{tools.keys.to_json}."
           }
         end
 

data/lib/phronomy/stream_callback_error.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Phronomy
+  # Raised when an Application stream callback fails and
+  # +stream_callback_error_policy+ is +:fail_task+.
+  #
+  # This error represents delivery failure, not Agent, LLM, Tool, or FSM
+  # execution failure. The Agent result is retained in {#result}, and the
+  # original Application exception is available through both
+  # {#original_error} and Ruby's +#cause+ chain.
+  #
+  # @api public
+  class StreamCallbackError < Error
+    # @return [Symbol] stream event type handled by the failing callback
+    attr_reader :event_type
+
+    # @return [Hash, nil] successful or suspended Agent result
+    attr_reader :result
+
+    # @return [Exception] original Application callback exception
+    attr_reader :original_error
+
+    def initialize(event_type:, original_error:, result: nil)
+      @event_type = event_type
+      @original_error = original_error
+      @result = result
+
+      super(
+        "Stream callback failed while handling #{event_type.inspect}: " \
+        "#{original_error.class}: #{original_error.message}"
+      )
+      set_backtrace(original_error.backtrace)
+    end
+  end
+end

data/lib/phronomy/testing/scheduler_helpers.rb

@@ -46,12 +46,21 @@ module Phronomy
         scheduler = Phronomy::Runtime::FakeScheduler.new
         scheduler.clock = clock if clock
         runtime = Phronomy::Runtime.new(scheduler: scheduler)
-        original = Phronomy::Runtime.instance
-        Phronomy::Runtime.instance = runtime
+        original = Phronomy::Runtime.default_if_initialized_for_test
+        Phronomy::Runtime.replace_default_for_test(runtime)
         begin
           yield scheduler, clock
         ensure
-          Phronomy::Runtime.instance = original
+          result = nil
+          begin
+            result = runtime.shutdown
+          ensure
+            Phronomy::Runtime.restore_default_for_test(original)
+          end
+          unless result&.cleanup_complete?
+            raise Phronomy::RuntimeShutdownError,
+              "Temporary test Runtime did not shut down completely"
+          end
         end
       end
     end