phronomy 0.7.1 → 0.8.0

data/lib/phronomy/agent/tool_executor.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    # Centralises tool execution routing based on {Tool::Base.execution_mode}.
+    #
+    # This is the single place in the framework that decides *how* a tool call is
+    # dispatched:
+    #
+    # - +:cooperative+       — dispatched via +Runtime#spawn+ through the configured
+    #                          scheduler. Under the +:fiber+ backend this avoids an
+    #                          extra OS thread; under the +:thread+ backend it is
+    #                          backed by +ThreadScheduler+ (one thread per task).
+    # - +:blocking_io+       — submitted to +BlockingAdapterPool+ when the runtime
+    #                          provides a pool; falls back to +Runtime#spawn+ otherwise.
+    # - +:cpu_bound+         — emits a deprecation-style warning then falls back to
+    #                          +:blocking_io+ routing (no process pool available yet).
+    # - +:external_process+  — falls back to +:blocking_io+ routing (no process
+    #                          manager available yet).
+    #
+    # All paths return an object that responds to +#await+ (+Phronomy::Task+ or
+    # +BlockingAdapterPool::PendingOperation+), so callers can collect results
+    # uniformly.
+    #
+    # @note Non-goals
+    #   ToolExecutor deliberately does NOT provide:
+    #   - A CPU-bound process pool. CPU-intensive tool work must be handled at the
+    #     application layer (e.g., fork, Sidekiq, separate OS processes). The
+    #     framework will not add a +ProcessPoolExecutor+ equivalent.
+    #   - An external process manager. Spawning or supervising subprocesses is
+    #     out of scope for this module.
+    #   - Additional core execution routes beyond scheduler-backed cooperative
+    #     execution and BlockingAdapterPool-backed blocking I/O isolation.
+    #     The +:cpu_bound+ and +:external_process+ modes are accepted for
+    #     compatibility but both fall back to +:blocking_io+ routing with a
+    #     one-time warning. If a genuinely new core execution route is needed,
+    #     a new ADR is required.
+    #   These non-goals follow from the cooperative-first, non-preemptive
+    #   concurrency model (ADR-010): framework components must not assume the
+    #   caller's concurrency model, and CPU/process management belongs to the
+    #   application layer.
+    #
+    # @api private
+    module ToolExecutor
+      # Tracks tool classes that have already emitted an execution_mode warning so
+      # that the same warning is only logged once per process lifetime.
+      WARNED_MODES = Set.new
+      WARNED_MODES_MUTEX = Mutex.new
+      private_constant :WARNED_MODES, :WARNED_MODES_MUTEX
+
+      # Dispatches a single tool call asynchronously according to its
+      # +execution_mode+ and returns an awaitable.
+      #
+      # @param tool               [Phronomy::Tool::Base] the tool instance to invoke
+      # @param args               [Hash]                 argument hash to pass to {Tool::Base#call}
+      # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil]
+      # @param runtime            [Phronomy::Runtime]    runtime to use for spawning
+      #                           (defaults to {Runtime.instance}; injectable for tests)
+      # @return [#await] a {Phronomy::Task} or {BlockingAdapterPool::PendingOperation}
+      # @api private
+      def self.call_async(tool:, args:, cancellation_token: nil, runtime: Phronomy::Runtime.instance)
+        ct = cancellation_token
+        mode = tool.class.execution_mode
+
+        # Warn and normalise unsupported modes to :blocking_io.
+        # Each (tool class, mode) pair emits the warning at most once per process
+        # lifetime to avoid log flooding in high-throughput scenarios.
+        if mode == :cpu_bound || mode == :external_process
+          warn_key = [tool.class.name, mode]
+          newly_warned = WARNED_MODES_MUTEX.synchronize { WARNED_MODES.add?(warn_key) }
+          if newly_warned
+            msg = if mode == :cpu_bound
+              "[Phronomy] Tool #{tool.class.name} declares execution_mode :cpu_bound, " \
+              "which has no dedicated executor. " \
+              "Falling back to blocking_io (BlockingAdapterPool). " \
+              "Use :blocking_io explicitly to suppress this warning."
+            else
+              "[Phronomy] Tool #{tool.class.name} declares execution_mode :external_process, " \
+              "which has no dedicated process manager. " \
+              "Falling back to blocking_io (BlockingAdapterPool)."
+            end
+            if Phronomy.configuration.logger
+              Phronomy.configuration.logger.warn(msg)
+            else
+              warn msg
+            end
+          end
+          mode = :blocking_io
+        end
+
+        pool = begin
+          runtime&.blocking_io
+        rescue
+          nil
+        end
+
+        if mode == :cooperative || pool.nil?
+          runtime.spawn(name: "tool-#{tool.class.name.to_s.split("::").last}") do
+            tool.call(args, cancellation_token: ct)
+          end
+        else
+          # Submit directly to pool — no wrapping Task thread required.
+          pool.submit(cancellation_token: ct) { tool.call(args, cancellation_token: ct) }
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/concurrency/async_queue.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Concurrency
+    # 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::Concurrency::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
+end