phronomy 0.7.0 → 0.7.1

data/lib/phronomy/agent/parallel_tool_chat.rb

@@ -5,21 +5,39 @@ module Phronomy
     # RubyLLM::Chat subclass that executes multiple tool calls concurrently.
     #
     # When the LLM returns more than one tool call in a single response, each
-    # tool is dispatched in a dedicated IO thread and all results are collected
-    # before being appended to the message history. This preserves a
-    # deterministic message order while reducing wall-clock latency when tools
-    # are IO-bound (HTTP calls, DB queries, etc.).
+    # 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 the agent is running inside an
-    # {AgentFSM} IO thread (i.e. when the +:phronomy_agent_parallel_tools+
-    # thread-local flag is +true+).  It is not used for direct synchronous
-    # +invoke+ calls so that the streaming callback state remains single-threaded.
+    # 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.
     # @api private
     class ParallelToolChat < RubyLLM::Chat
+      # @param max_parallel_tools [Integer] maximum simultaneous tool executions
+      # @param cancellation_token [Phronomy::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)
+        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
+
       private
 
       # Overrides RubyLLM::Chat#handle_tool_calls to parallelise execution
@@ -29,7 +47,8 @@ module Phronomy
       #   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 — one IO thread per tool call.
+      #   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.
       #
@@ -52,29 +71,48 @@ module Phronomy
         end
 
         # Phase 2 — parallel tool execution.
-        # Honour the per-agent concurrency cap (max_parallel_tools DSL).
-        # Tool calls are processed in batches of at most `max` threads;
-        # batches run sequentially so the total in-flight thread count never
-        # exceeds the limit.
+        # :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.
         #
-        # Check for cancellation before dispatching each batch so that
-        # already-cancelled tokens do not start new LLM/tool-round-trips.
-        ct = Thread.current[:phronomy_cancellation_token]
-        max = Thread.current[:phronomy_max_parallel_tools] || 10
-        thread_results = tool_calls.each_slice(max).flat_map do |batch|
+        # Both Phronomy::Task and BlockingAdapterPool::PendingOperation support
+        # #await, 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
 
-          threads = batch.map do |tool_call|
-            Thread.new { {tool_call: tool_call, result: execute_tool(tool_call)} }
+          # 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
+
+            awaitable = Phronomy::ToolExecutor.call_async(
+              tool: tool,
+              args: tc.arguments,
+              cancellation_token: ct
+            )
+            {tool_call: tc, awaitable: awaitable, result: nil}
+          end
+
+          # Await all dispatched operations in original order.
+          dispatched.map do |item|
+            result = item[:awaitable] ? item[:awaitable].await : item[:result]
+            {tool_call: item[:tool_call], result: result}
           end
-          threads.map(&:value)
         end
 
         # Phase 3 — post-execution callbacks and message recording (sequential).
         halt_result = nil
-        thread_results.each do |item|
+        tool_results.each do |item|
           result = item[:result]
           @on[:tool_result]&.call(result)
           tool_payload = result.is_a?(RubyLLM::Tool::Halt) ? result.content : result
@@ -87,6 +125,25 @@ module Phronomy
         reset_tool_choice if forced_tool_choice?
         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}."
+          }
+        end
+
+        Phronomy::ToolExecutor.call_async(
+          tool: tool,
+          args: tool_call.arguments,
+          cancellation_token: @cancellation_token
+        ).await
+      end
     end
   end
 end

data/lib/phronomy/agent/react_agent.rb

@@ -13,6 +13,10 @@ module Phronomy
         caller_meta = {}
         caller_meta[:user_id] = config[:user_id] if config[:user_id]
         caller_meta[:session_id] = config[:session_id] if config[:session_id]
+        if (ic = config[:invocation_context])
+          caller_meta[:task_id] = ic.task_id if ic.task_id
+          caller_meta[:parent_task_id] = ic.parent_task_id if ic.parent_task_id
+        end
 
         trace("agent.invoke", input: input, **caller_meta) do |_span|
           # Run input guardrails before any LLM interaction.
@@ -68,6 +72,10 @@ module Phronomy
         caller_meta = {}
         caller_meta[:user_id] = config[:user_id] if config[:user_id]
         caller_meta[:session_id] = config[:session_id] if config[:session_id]
+        if (ic = config[:invocation_context])
+          caller_meta[:task_id] = ic.task_id if ic.task_id
+          caller_meta[:parent_task_id] = ic.parent_task_id if ic.parent_task_id
+        end
 
         trace("agent.invoke", input: input, **caller_meta) do |_span|
           run_input_guardrails!(input)

data/lib/phronomy/async_queue.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+module Phronomy
+  # A thread-safe FIFO queue for passing values between concurrent tasks.
+  #
+  # Wraps +Thread::Queue+ so that callers do not need to reference the Ruby
+  # standard-library type directly.  A future implementation may replace the
+  # backing primitive without changing call sites.
+  #
+  # @example Producer / consumer
+  #   queue = Phronomy::AsyncQueue.new
+  #   Runtime.instance.spawn { queue.push(expensive_io()) }
+  #   value = queue.pop   # blocks until the producer pushes
+  # @api private
+  class AsyncQueue
+    # @param max_size [Integer, nil] optional upper bound on queue depth.
+    #   When set, {#push} blocks the caller until a slot is available.
+    # @api private
+    def initialize(max_size: nil)
+      @queue = max_size ? SizedQueue.new(max_size) : Thread::Queue.new
+      @max_size = max_size
+    end
+
+    # Enqueues +item+.
+    # In a cooperative scheduler context with a bounded queue (max_size:), suspends
+    # the current Fiber via a scheduler signal when the queue is full rather than
+    # blocking the OS thread.  Without a scheduler, falls back to the standard
+    # SizedQueue blocking behaviour.
+    # @param item [Object] value to enqueue
+    # @return [self]
+    # @api private
+    def push(item)
+      scheduler = Phronomy::Runtime::Scheduler.current
+      if scheduler && @max_size
+        _push_cooperative(scheduler, item)
+      else
+        @queue.push(item)
+        scheduler.raise_signal(@coop_signal) if scheduler && @coop_signal
+      end
+      self
+    end
+
+    # Dequeues and returns the next item.
+    # In a cooperative scheduler context, suspends the current Fiber (yielding
+    # control back to the scheduler) rather than blocking the OS thread.
+    #
+    # When +timeout+ is given the semantics depend on the active backend:
+    #
+    # * **Thread backend** (`:thread`) — uses real wall-clock time via
+    #   +Thread::Queue#pop(timeout:)+.  Requires Ruby 3.2+.
+    #   Returns +nil+ if no item arrives within the specified number of real seconds.
+    # * **DeterministicScheduler / `:fiber` backend** — uses the scheduler's
+    #   *virtual time* (+scheduler.virtual_time+).  The timeout elapses only when
+    #   the virtual clock is advanced (e.g. via {Phronomy::Testing::FakeClock#advance}).
+    #   In tests this means the timeout is fully deterministic and does not depend on
+    #   actual elapsed wall time.  However, in production `:fiber` mode the timeout
+    #   may never expire unless the scheduler explicitly advances virtual time.
+    #
+    # @note The `:fiber` backend is **EXPERIMENTAL**.  Real-time timeout behaviour
+    #   in production workloads is not guaranteed and may differ from wall-clock
+    #   expectations.
+    # @note **Cooperative timeout limitation**: on the cooperative path, the
+    #   deadline is re-checked *after* a wake-up signal arrives.  If virtual time
+    #   has already passed the deadline when the consumer is woken by a producer
+    #   push, the consumer returns +nil+ rather than the pushed item.  Without any
+    #   wake-up signal the waiting Fiber remains suspended even after
+    #   +scheduler.advance+ — the timeout does not self-fire.
+    # @param timeout [Numeric, nil] seconds to wait before returning +nil+.
+    #   Semantics are wall-clock on `:thread` and virtual-time on `:fiber`.
+    # @return [Object, nil] the next item, or +nil+ when timeout expires
+    # @api private
+    def pop(timeout: nil)
+      scheduler = Phronomy::Runtime::Scheduler.current
+      if scheduler
+        _pop_cooperative(scheduler, timeout: timeout)
+      elsif timeout
+        @queue.pop(timeout: timeout)
+      else
+        @queue.pop
+      end
+    end
+
+    # Returns the current number of items in the queue.
+    # @return [Integer]
+    # @api private
+    def size
+      @queue.size
+    end
+
+    # Returns +true+ when the queue contains no items.
+    # @return [Boolean]
+    # @api private
+    def empty?
+      @queue.empty?
+    end
+
+    # Closes the queue.  Subsequent {#pop} calls raise +ClosedQueueError+.
+    # @return [self]
+    # @api private
+    def close
+      @queue.close
+      self
+    end
+
+    private
+
+    # Cooperative pop for DeterministicScheduler context.
+    # Suspends the current Fiber via the scheduler's signal mechanism rather than
+    # blocking the OS thread.  Because cooperative mode is single-threaded, the
+    # empty?/pop pair is race-free (no other Fiber can run between the two calls).
+    # After dequeuing, notifies any push-waiter so that a backpressure-suspended
+    # producer can be unblocked.
+    # @api private
+    # @param scheduler [Runtime::Scheduler]
+    # @param timeout [Numeric, nil]
+    # @return [Object, nil]
+    def _pop_cooperative(scheduler, timeout:)
+      @coop_signal ||= scheduler.new_signal
+      deadline = timeout ? (scheduler.virtual_time + timeout) : nil
+
+      loop do
+        unless @queue.empty?
+          item = @queue.pop(timeout: 0)
+          # Notify a push-waiter (bounded queue) that a slot opened up.
+          scheduler.raise_signal(@push_signal) if @push_signal
+          return item
+        end
+        return nil if deadline && scheduler.virtual_time >= deadline
+        scheduler.wait_for_signal(@coop_signal)
+        return nil if deadline && scheduler.virtual_time >= deadline
+      end
+    end
+
+    # Cooperative push for DeterministicScheduler context with a bounded queue.
+    # Suspends the current Fiber via a scheduler signal when the queue is full,
+    # rather than blocking the OS thread.
+    # @api private
+    # @param scheduler [Runtime::Scheduler]
+    # @param item [Object]
+    # @return [void]
+    def _push_cooperative(scheduler, item)
+      @push_signal ||= scheduler.new_signal
+
+      loop do
+        unless @queue.size >= @max_size
+          @queue.push(item)
+          # Notify any pop-waiter that an item is now available.
+          scheduler.raise_signal(@coop_signal) if @coop_signal
+          return
+        end
+        scheduler.wait_for_signal(@push_signal)
+      end
+    end
+  end
+end