phronomy 0.6.0 → 0.7.1

data/lib/phronomy/task_group.rb

@@ -0,0 +1,265 @@
+# frozen_string_literal: true
+
+module Phronomy
+  # Manages a bounded set of concurrent {Task}s with structured concurrency.
+  #
+  # Enforces an upper bound on simultaneously running tasks (+limit+).
+  # When the limit is reached, {#spawn} blocks the caller until a slot
+  # becomes available.  Results are always returned in the order tasks
+  # were spawned, regardless of completion order.
+  #
+  # A configurable +failure_policy+ controls how errors propagate:
+  # - +:fail_fast+ (default) — cancels all remaining tasks on the first error
+  # - +:collect_all+ — waits for every task to complete, then raises the first error
+  # - +:skip_failed+ — ignores failed tasks and returns only successful results
+  #
+  # {#cancel_all!} cancels every task in the group and joins them, guaranteeing
+  # that the active child task count reaches zero before returning.
+  #
+  # @example Parallel tool calls with a concurrency cap
+  #   group = Phronomy::TaskGroup.new(limit: 5)
+  #   tasks = items.map { |item| group.spawn { process(item) } }
+  #   results = group.await_all   # Array in spawn order
+  #
+  # @example Collect-all failure policy
+  #   group = Phronomy::TaskGroup.new(failure_policy: :collect_all)
+  #   …
+  class TaskGroup
+    # Valid failure policies.
+    FAILURE_POLICIES = %i[fail_fast collect_all skip_failed].freeze
+
+    # @param limit          [Integer, Float::INFINITY] maximum simultaneous active tasks
+    # @param failure_policy [Symbol] one of {FAILURE_POLICIES} (default +:fail_fast+)
+    # @param runtime        [Runtime, nil] runtime used to spawn tasks via {Runtime#spawn};
+    #   when +nil+, tasks are created directly via +Task.new+ (backward-compatible mode).
+    #   Pass +runtime: self+ from {Runtime#task_group} to keep task execution consistent
+    #   with the configured scheduler backend.
+    # @api private
+    def initialize(limit: Float::INFINITY, failure_policy: :fail_fast, runtime: nil)
+      raise ArgumentError, "unknown failure_policy: #{failure_policy}" unless FAILURE_POLICIES.include?(failure_policy)
+
+      @limit = limit
+      @failure_policy = failure_policy
+      @runtime = runtime
+      @tasks = []
+      @mutex = Mutex.new
+      @cond = ConditionVariable.new
+      @active = 0
+    end
+
+    # Spawns a new task within the group.
+    # Blocks if the number of currently active tasks equals +limit+.
+    #
+    # @yield block to execute concurrently
+    # @return [Task] the spawned task
+    # @api private
+    def spawn(&block)
+      wait_for_slot!
+
+      task = if @runtime
+        @runtime.spawn(name: "task-group-worker") do
+          block.call
+        ensure
+          release_slot!
+        end
+      else
+        Task.new do
+          block.call
+        ensure
+          release_slot!
+        end
+      end
+
+      @mutex.synchronize { @tasks << task }
+      task
+    end
+
+    # Waits for all spawned tasks to complete.
+    # Returns results in spawn order.
+    #
+    # Failure behaviour is controlled by the +failure_policy+ set at
+    # construction time:
+    # - +:fail_fast+    — raises the first error after cancelling unfinished tasks
+    # - +:collect_all+  — waits for all tasks, then raises the first error
+    # - +:skip_failed+  — returns only the values of successful tasks
+    #
+    # @return [Array] results in spawn order (or successful-only for :skip_failed)
+    # @raise [Exception] when any task failed (except :skip_failed)
+    # @api private
+    def await_all
+      tasks = @mutex.synchronize { @tasks.dup }
+      return [] if tasks.empty?
+
+      if Phronomy::Runtime::Scheduler.current
+        _await_all_cooperative(tasks)
+      else
+        _await_all_threaded(tasks)
+      end
+    end
+
+    private
+
+    # Cooperative await_all for DeterministicScheduler context.
+    # Uses on_complete callbacks + AsyncQueue to observe task completions in
+    # arrival order (not spawn order), matching the fail-fast semantics of the
+    # threaded path.  AsyncQueue#pop suspends the current Fiber cooperatively
+    # rather than blocking the OS thread.
+    # @api private
+    # @param tasks [Array<Task>]
+    # @return [Array]
+    def _await_all_cooperative(tasks)
+      completion_q = AsyncQueue.new
+      tasks.each_with_index do |task, idx|
+        task.on_complete do |value, error|
+          completion_q.push({index: idx, value: value, error: error})
+        end
+      end
+
+      entries = Array.new(tasks.length)
+      cancelled = false
+      fail_fast_error = nil
+
+      tasks.length.times do
+        entry = completion_q.pop  # cooperative suspend via scheduler signal
+        entries[entry[:index]] = entry
+
+        if entry[:error] && @failure_policy == :fail_fast && !cancelled
+          cancelled = true
+          fail_fast_error = entry[:error]
+          tasks.each { |t| t.cancel! unless t.done? }
+        end
+      end
+
+      case @failure_policy
+      when :fail_fast
+        raise fail_fast_error if fail_fast_error
+        entries.map { |r| r[:value] }
+      when :skip_failed
+        entries.filter_map { |r| r[:value] unless r[:error] }
+      else # :collect_all
+        errors = entries.filter_map { |r| r[:error] }
+        raise errors.first if errors.any?
+        entries.map { |r| r[:value] }
+      end
+    end
+
+    # Thread-blocking await_all for ThreadBackend / ImmediateBackend context.
+    # Uses Task#on_complete callbacks instead of spawning N additional watcher
+    # tasks (Issue #328).  on_complete receives the task's value and error
+    # directly — no await call is needed, eliminating the risk of a self-join
+    # when the callback fires inside the task's own execution thread.
+    def _await_all_threaded(tasks)
+      completion_q = Queue.new
+      tasks.each_with_index do |task, idx|
+        task.on_complete do |value, error|
+          completion_q.push({index: idx, value: value, error: error})
+        end
+      end
+
+      entries = Array.new(tasks.length)
+      cancelled = false
+      # The error that triggered fail_fast cancellation (tracked separately so
+      # we raise it rather than a secondary CancellationError from cancelled tasks).
+      fail_fast_error = nil
+
+      tasks.length.times do
+        entry = completion_q.pop
+        entries[entry[:index]] = entry
+
+        if entry[:error] && @failure_policy == :fail_fast && !cancelled
+          cancelled = true
+          fail_fast_error = entry[:error]
+          tasks.each { |t| t.cancel! unless t.done? }
+        end
+      end
+
+      case @failure_policy
+      when :fail_fast
+        raise fail_fast_error if fail_fast_error
+        entries.map { |r| r[:value] }
+      when :skip_failed
+        entries.filter_map { |r| r[:value] unless r[:error] }
+      else # :collect_all
+        errors = entries.filter_map { |r| r[:error] }
+        raise errors.first if errors.any?
+        entries.map { |r| r[:value] }
+      end
+    end
+
+    public
+
+    # Cancels all tasks currently in the group and waits for each to finish.
+    # After this method returns, the active child task count is guaranteed to
+    # be zero.
+    #
+    # Note: if a task is cancelled before its block has started executing, the
+    # internal +ensure+ clause inside the block may not run, so @active is
+    # reset explicitly after all tasks are joined.
+    #
+    # @return [self]
+    # @api private
+    def cancel_all!
+      tasks = @mutex.synchronize { @tasks.dup }
+      tasks.each(&:cancel!)
+      tasks.each do |t|
+        t.join
+      rescue
+        nil
+      end
+      # Force @active to zero: tasks cancelled before block execution starts
+      # may not decrement @active via their ensure clause.
+      scheduler = Phronomy::Runtime::Scheduler.current
+      if scheduler && @coop_signal
+        @active = 0
+        scheduler.raise_signal_all(@coop_signal)
+      else
+        @mutex.synchronize do
+          @active = 0
+          @cond.broadcast
+        end
+      end
+      self
+    end
+
+    # Returns the number of currently executing child tasks.
+    # @return [Integer]
+    # @api private
+    def active_task_count
+      @mutex.synchronize { @active }
+    end
+
+    private
+
+    def wait_for_slot!
+      scheduler = Phronomy::Runtime::Scheduler.current
+      if scheduler
+        @coop_signal ||= scheduler.new_signal
+        loop do
+          if @active < @limit
+            @active += 1
+            return
+          end
+          scheduler.wait_for_signal(@coop_signal)
+        end
+      else
+        @mutex.synchronize do
+          @cond.wait(@mutex) while @active >= @limit
+          @active += 1
+        end
+      end
+    end
+
+    def release_slot!
+      scheduler = Phronomy::Runtime::Scheduler.current
+      if scheduler && @coop_signal
+        @active -= 1
+        scheduler.raise_signal(@coop_signal)
+      else
+        @mutex.synchronize do
+          @active -= 1
+          @cond.signal
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/testing/fake_clock.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Testing
+    # A deterministic, manually-advanced clock for use in tests.
+    #
+    # Replaces real +Process.clock_gettime+ calls so that time-sensitive code
+    # can be tested without relying on wall-clock sleeps.
+    #
+    # @example
+    #   clock = Phronomy::Testing::FakeClock.new
+    #   clock.now        # => 0.0
+    #   clock.advance(5) # advance by 5 seconds
+    #   clock.now        # => 5.0
+    class FakeClock
+      # @return [Float] the current logical time in seconds since the epoch (t=0)
+      attr_reader :now
+
+      def initialize
+        @now = 0.0
+        @callbacks = [] # [[fire_at, block], ...]
+        @mutex = Mutex.new
+      end
+
+      # Advance the clock by +seconds+ and fire any registered callbacks whose
+      # deadline has passed.
+      #
+      # @param seconds [Numeric]
+      # @return [self]
+      # @api private
+      def advance(seconds)
+        @mutex.synchronize do
+          @now += seconds.to_f
+          fire_expired_callbacks!
+        end
+        self
+      end
+
+      # Register a one-shot callback that fires when the clock reaches +at+.
+      #
+      # @param at [Numeric] logical time to fire
+      # @yield called with no arguments when the clock reaches +at+
+      # @return [self]
+      # @api private
+      def at(at, &block)
+        @mutex.synchronize { @callbacks << [at.to_f, block] }
+        self
+      end
+
+      # Schedule a one-shot callback to fire after +seconds+ from the current
+      # logical time.  This is the same interface as {Runtime::TimerQueue#schedule}
+      # so that a +FakeClock+ can be passed as a +timer_queue:+ argument in tests.
+      #
+      # @param seconds [Numeric] delay in logical seconds
+      # @yield called when the clock reaches the scheduled time
+      # @return [self]
+      # @api private
+      def schedule(seconds:, &block)
+        at(@now + seconds.to_f, &block)
+      end
+
+      # Returns the number of pending (un-fired) callbacks.
+      # @return [Integer]
+      # @api private
+      def pending_callbacks
+        @mutex.synchronize { @callbacks.size }
+      end
+
+      # Returns the logical time of the next pending callback, or +nil+ if
+      # there are no pending callbacks.
+      #
+      # @return [Float, nil]
+      # @api private
+      def next_timer_at
+        @mutex.synchronize { @callbacks.min_by { |(t, _)| t }&.first }
+      end
+
+      # Advance the clock exactly to the next pending callback and fire it.
+      # Raises +RuntimeError+ when there are no pending callbacks.
+      #
+      # @return [self]
+      # @api private
+      def advance_to_next_timer
+        target = next_timer_at
+        raise "No pending timers to advance to" unless target
+
+        advance(target - @now)
+      end
+
+      # Returns descriptive entries for all pending callbacks.
+      # Used by {Phronomy::Runtime::FakeScheduler#pending_timers}.
+      #
+      # @return [Array<Hash>] each entry: +{ fire_at:, description: nil }+
+      # @api private
+      def pending_timer_entries
+        @mutex.synchronize do
+          @callbacks.sort_by { |(t, _)| t }.map { |(t, _)| {fire_at: t, description: nil} }
+        end
+      end
+
+      private
+
+      def fire_expired_callbacks!
+        fired, @callbacks = @callbacks.partition { |(t, _)| t <= @now }
+        fired.sort_by { |(t, _)| t }.each { |(_, cb)| cb.call }
+      end
+    end
+  end
+end

data/lib/phronomy/testing/fake_scheduler.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Testing
+    # A deterministic event dispatcher for use in tests.
+    #
+    # Wraps a {Thread::Queue} and dispatches events one at a time via {#tick}
+    # or drains all pending events via {#tick_until_idle}.  Tests can inspect
+    # queue depth and verify event ordering without wall-clock sleeps.
+    #
+    # @example
+    #   scheduler = Phronomy::Testing::FakeScheduler.new
+    #   scheduler.post(:a)
+    #   scheduler.post(:b)
+    #   scheduler.queue_depth   # => 2
+    #   scheduler.tick          # dispatches :a
+    #   scheduler.queue_depth   # => 1
+    #   scheduler.tick_until_idle
+    #   scheduler.dispatched    # => [:a, :b]
+    class FakeScheduler
+      # @return [Array] all events dispatched so far (in order)
+      attr_reader :dispatched
+
+      def initialize
+        @queue = Thread::Queue.new
+        @dispatched = []
+        @handlers = {}
+      end
+
+      # Enqueue an event for later dispatch.
+      #
+      # @param event [Object]
+      # @return [self]
+      # @api private
+      def post(event)
+        @queue.push(event)
+        self
+      end
+
+      # Dispatch the next queued event.
+      # Calls the registered handler (if any) and records the event.
+      # Returns the dispatched event, or +nil+ if the queue is empty.
+      #
+      # @return [Object, nil]
+      # @api private
+      def tick
+        return nil if @queue.empty?
+
+        event = begin
+          @queue.pop(true)
+        rescue
+          nil
+        end
+        return nil unless event
+
+        @dispatched << event
+        handler = @handlers[event.class] || @handlers[:any]
+        handler&.call(event)
+        event
+      end
+
+      # Dispatch events until the queue is empty.
+      # Bounded by +max_ticks+ to prevent infinite loops.
+      #
+      # @param max_ticks [Integer]
+      # @return [Integer] number of events dispatched
+      # @api private
+      def tick_until_idle(max_ticks: 1000)
+        count = 0
+        while !@queue.empty? && count < max_ticks
+          tick
+          count += 1
+        end
+        count
+      end
+
+      # Returns the number of events waiting to be dispatched.
+      # @return [Integer]
+      # @api private
+      def queue_depth
+        @queue.size
+      end
+
+      # Register a handler block for events of the given class.
+      # Use +:any+ to handle all event types.
+      #
+      # @param klass [Class, :any]
+      # @yield [event]
+      # @return [self]
+      # @api private
+      def on(klass, &block)
+        @handlers[klass] = block
+        self
+      end
+
+      # Returns true when the queue is empty.
+      # @return [Boolean]
+      # @api private
+      def idle?
+        @queue.empty?
+      end
+    end
+  end
+end

data/lib/phronomy/testing/scheduler_helpers.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Testing
+    # RSpec helper module that provides a deterministic {Runtime} backed by
+    # {Phronomy::Runtime::FakeScheduler}.
+    #
+    # Include this module in your RSpec describe/context blocks and call
+    # {#with_fake_scheduler} to run a block of code inside a fully
+    # synchronous, event-logged runtime.
+    #
+    # @example Basic usage (no clock)
+    #   include Phronomy::Testing::SchedulerHelpers
+    #
+    #   it "records completed events" do
+    #     with_fake_scheduler do |sched|
+    #       Phronomy::Runtime.instance.spawn(name: "my-task") { 42 }
+    #       expect(sched.event_log.map { |e| e[:type] }).to include(:completed)
+    #     end
+    #   end
+    #
+    # @example With a FakeClock
+    #   include Phronomy::Testing::SchedulerHelpers
+    #
+    #   it "surfaces pending timers" do
+    #     clock = Phronomy::Testing::FakeClock.new
+    #     with_fake_scheduler(clock: clock) do |sched|
+    #       clock.schedule(seconds: 5) { :fired }
+    #       expect(sched.pending_timers.first[:fire_at]).to eq(5.0)
+    #     end
+    #   end
+    module SchedulerHelpers
+      # Run +block+ with a {Phronomy::Runtime} that uses
+      # {Phronomy::Runtime::FakeScheduler}.
+      #
+      # The global runtime is replaced for the duration of the block and
+      # restored afterwards, whether the block raises or not.
+      #
+      # @param clock [Phronomy::Testing::FakeClock, nil]
+      #   Optional fake clock to inject into the scheduler for timer support
+      #   and event timestamping.
+      # @yield [scheduler, clock] the {Runtime::FakeScheduler} and the clock
+      # @return [Object] the return value of the block
+      # @api private
+      def with_fake_scheduler(clock: nil)
+        scheduler = Phronomy::Runtime::FakeScheduler.new
+        scheduler.clock = clock if clock
+        runtime = Phronomy::Runtime.new(scheduler: scheduler)
+        original = Phronomy::Runtime.instance
+        Phronomy::Runtime.instance = runtime
+        begin
+          yield scheduler, clock
+        ensure
+          Phronomy::Runtime.instance = original
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/testing.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Phronomy
+  # Test helpers for deterministic, timer-independent testing.
+  #
+  # @example
+  #   require "phronomy/testing"
+  #   clock = Phronomy::Testing::FakeClock.new
+  #   scheduler = Phronomy::Testing::FakeScheduler.new
+  module Testing
+  end
+end

data/lib/phronomy/tool/agent_tool.rb

@@ -35,6 +35,7 @@ module Phronomy
         # @param description  [String, nil] description exposed to the LLM;
         #   defaults to "Delegates to <AgentClassName>"
         # @return [Class] an anonymous Phronomy::Tool::AgentTool subclass
+        # @api public
         def from_agent(agent_class, tool_name: nil, description: nil)
           raise ArgumentError, "agent_class must be a Class" unless agent_class.is_a?(Class)