phronomy 0.17.0 → 0.19.0

data/lib/phronomy/engine/runtime/runtime_metrics.rb

@@ -1,116 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  class Runtime
-    # Internal store for task-centric counters and latency samples.
-    #
-    # All access is mutex-protected.  The ring buffers for wait/run times are
-    # bounded to {WINDOW} samples so that long-lived runtimes do not grow
-    # unbounded.
-    # @api private
-    class RuntimeMetrics
-      WINDOW = 1000
-      private_constant :WINDOW
-
-      def initialize
-        @mutex = Mutex.new
-        @active_by_type = Hash.new(0)
-        @wait_ms = []
-        @run_ms = []
-        @cancelled = Hash.new(0)
-        @failed = Hash.new(0)
-        @starvation_count = 0
-      end
-
-      # Records that a new task of +type+ has been spawned.
-      # @param type [Symbol]
-      # @return [void]
-      # @api private
-      def record_start(type)
-        @mutex.synchronize { @active_by_type[type] += 1 }
-      end
-
-      # Appends a wait-time sample (milliseconds from spawn to start).
-      # @param wait_ms [Float]
-      # @return [void]
-      # @api private
-      def record_wait(wait_ms)
-        @mutex.synchronize do
-          @wait_ms << wait_ms
-          @wait_ms.shift if @wait_ms.size > WINDOW
-        end
-      end
-
-      # Records completion of a task (decrements active count, appends run time).
-      # @param type    [Symbol]
-      # @param outcome [:completed, :cancelled, :failed]
-      # @param run_start_ms [Integer] monotonic millisecond timestamp from task start
-      # @return [void]
-      # @api private
-      def record_end(type, outcome, run_start_ms)
-        run_ms = Process.clock_gettime(Process::CLOCK_MONOTONIC, :millisecond) - run_start_ms
-        @mutex.synchronize do
-          @active_by_type[type] = [@active_by_type[type] - 1, 0].max
-          @run_ms << run_ms
-          @run_ms.shift if @run_ms.size > WINDOW
-          case outcome
-          when :cancelled then @cancelled[type] += 1
-          when :failed then @failed[type] += 1
-          end
-        end
-      end
-
-      # Increments the CPU-starvation counter (task ran without yielding over
-      # the configured +blocking_detect_threshold_ms+ threshold).
-      # @return [void]
-      # @api private
-      def increment_starvation
-        @mutex.synchronize { @starvation_count += 1 }
-      end
-
-      # Returns the current starvation counter value.
-      # @return [Integer]
-      # @api private
-      def starvation_count
-        @mutex.synchronize { @starvation_count }
-      end
-
-      # Returns the full task-centric metrics hash (see {Runtime#task_snapshot}).
-      # @return [Hash{Symbol => Numeric}]
-      # @api private
-      def snapshot
-        @mutex.synchronize do
-          active = @active_by_type.dup
-          wait = @wait_ms.dup
-          run = @run_ms.dup
-          cancelled = @cancelled.values.sum
-          failed = @failed.values.sum
-          starvation = @starvation_count
-          {
-            active_agent_tasks: active[:agent].to_i,
-            active_tool_tasks: active[:tool].to_i,
-            active_workflow_tasks: active[:workflow].to_i,
-            active_llm_tasks: active[:llm].to_i,
-            task_wait_time_p50_ms: _percentile(wait, 50),
-            task_wait_time_p95_ms: _percentile(wait, 95),
-            task_run_time_p50_ms: _percentile(run, 50),
-            task_run_time_p95_ms: _percentile(run, 95),
-            cancelled_tasks: cancelled,
-            failed_tasks: failed,
-            non_yield_threshold_violation_count: starvation
-          }
-        end
-      end
-
-      private
-
-      def _percentile(samples, pct)
-        return 0.0 if samples.empty?
-
-        sorted = samples.sort
-        idx = ((pct / 100.0) * (sorted.size - 1)).round
-        sorted[idx].round(3)
-      end
-    end
-  end
-end

data/lib/phronomy/engine/runtime/scheduler.rb

@@ -1,98 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  class Runtime
-    # Abstract base class for Runtime scheduler backends.
-    #
-    # A scheduler is responsible for turning +Runtime#spawn+ calls into
-    # runnable {Task} objects.  Concrete subclasses decide whether tasks
-    # execute on threads, Fibers, or some other execution primitive.
-    #
-    # The interface is intentionally minimal: callers only see {Task}
-    # objects and never interact with the scheduler directly.
-    class Scheduler
-      # Thread-local key under which the active scheduler is stored.
-      # Shared with {Task::FiberBackend} (same symbol).
-      # @api private
-      SCHEDULER_KEY = :phronomy_deterministic_scheduler
-
-      # Returns the scheduler currently dispatching on this OS thread, or +nil+
-      # when running outside a cooperative (Fiber-based) scheduler context.
-      #
-      # Uses +Thread#thread_variable_get+ (not +Thread#[]+) so that the value is
-      # visible across all Fibers running on the same OS thread.
-      #
-      # @return [Scheduler, nil]
-      # @api private
-      def self.current
-        Thread.current.thread_variable_get(SCHEDULER_KEY)
-      end
-
-      # Creates a new scheduler-aware signal object for this scheduler.
-      # Signalling primitives use this instead of +ConditionVariable+ when a
-      # cooperative scheduler is active.
-      #
-      # Default implementation raises +NotImplementedError+.  Subclasses that
-      # support cooperative suspension (e.g. {DeterministicScheduler}) must
-      # override this.
-      #
-      # @return [Object] an opaque signal handle understood by {#wait_for_signal}
-      #   and {#raise_signal}
-      # @api private
-      def new_signal
-        raise NotImplementedError, "#{self.class}#new_signal is not implemented"
-      end
-
-      # Suspends the current execution unit (Fiber or Thread) until +signal+ is
-      # raised via {#raise_signal}.
-      #
-      # @param signal [Object] signal handle returned by {#new_signal}
-      # @return [void]
-      # @api private
-      def wait_for_signal(signal)
-        raise NotImplementedError, "#{self.class}#wait_for_signal is not implemented"
-      end
-
-      # Wakes up one waiter suspended on +signal+.
-      #
-      # @param signal [Object] signal handle returned by {#new_signal}
-      # @return [void]
-      # @api private
-      def raise_signal(signal)
-        raise NotImplementedError, "#{self.class}#raise_signal is not implemented"
-      end
-
-      # Wakes up all waiters suspended on +signal+.
-      #
-      # @param signal [Object] signal handle returned by {#new_signal}
-      # @return [void]
-      # @api private
-      def raise_signal_all(signal)
-        raise NotImplementedError, "#{self.class}#raise_signal_all is not implemented"
-      end
-
-      # Spawns a new task.
-      #
-      # @param name   [String, nil] optional human-readable label
-      # @param parent [Task, nil]   parent task for cancellation propagation
-      # @yield block to execute concurrently (or synchronously, depending on
-      #   the concrete scheduler)
-      # @return [Task]
-      # @api private
-      def spawn(name:, parent:, &block)
-        raise NotImplementedError, "#{self.class}#spawn is not implemented"
-      end
-
-      # Cooperative yield point.
-      #
-      # Default implementation is a no-op.  Thread-based subclasses should
-      # override with +Thread.pass+; fiber-based subclasses should switch to the
-      # next runnable fiber.
-      # @return [void]
-      # @api private
-      def yield
-        # no-op by default; subclasses override
-      end
-    end
-  end
-end

data/lib/phronomy/engine/runtime/scheduler_timer_adapter.rb

@@ -1,79 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  class Runtime
-    # A drop-in replacement for {TimerQueue} that delegates timer scheduling to
-    # a {DeterministicScheduler} instead of spawning a dedicated background OS thread.
-    #
-    # When a {Runtime} is backed by {DeterministicScheduler} (e.g. the +:fiber+
-    # runtime backend), {Runtime#timer_queue} returns an instance of this adapter
-    # rather than a {TimerQueue}.  This eliminates the +phronomy-timer-queue+
-    # background thread for Fiber-based runtimes.
-    #
-    # Timer callbacks are fired during {DeterministicScheduler#run_until_idle}
-    # when {DeterministicScheduler#autorun?} is +true+ (i.e. the +:fiber+ backend).
-    # They can also be fired explicitly by calling
-    # {DeterministicScheduler#fire_real_timers}.
-    #
-    # == Known Limitation (Issue #331)
-    #
-    # Timers that require an actual wall-clock sleep (e.g. a deadline of 10 s
-    # from now that will not be reached until real time elapses) will not fire
-    # automatically: +run_until_idle+ does not block waiting for future deadlines.
-    # This is an accepted limitation of the current stepping-stone implementation.
-    # Full resolution requires integrating the cooperative scheduler with the
-    # {EventLoop} tick cycle so that a single event-loop iteration checks both
-    # ready Fibers and expired wall-clock timers.
-    #
-    # Use the +:thread+ runtime backend (default) for production workloads that
-    # depend on real-time deadline enforcement.
-    #
-    # @see DeterministicScheduler#schedule_real_after
-    # @see DeterministicScheduler#fire_real_timers
-    # Bridges wall-clock timers to the cooperative {DeterministicScheduler}.
-    #
-    # Registers a recurring timer callback with the scheduler's {TimerQueue}
-    # so that Fiber-based tasks can await real time without blocking OS threads.
-    # @api private
-    class SchedulerTimerAdapter
-      # @param scheduler [DeterministicScheduler]
-      # @api private
-      def initialize(scheduler)
-        @scheduler = scheduler
-      end
-
-      # Schedules a one-shot callback to fire after +seconds+ from now.
-      # Delegates to {DeterministicScheduler#schedule_real_after}.
-      #
-      # Raises {PoolShutdownError} after {#shutdown} has been called, matching
-      # the behaviour of {TimerQueue#schedule}.
-      #
-      # @param seconds [Numeric] delay before the callback fires
-      # @yield called when the deadline is reached
-      # @return [self]
-      # @api private
-      def schedule(seconds:, &callback)
-        raise Phronomy::PoolShutdownError, "SchedulerTimerAdapter has been shut down" if @stopped
-
-        @scheduler.schedule_real_after(seconds, &callback)
-        self
-      end
-
-      # No-op: there is no background thread to stop.
-      # Present for API compatibility with {TimerQueue}.
-      # @return [self]
-      # @api private
-      def shutdown
-        @stopped = true
-        self
-      end
-
-      # Returns the number of pending (not yet fired) callbacks.
-      # @return [Integer]
-      # @api private
-      def pending_count
-        @scheduler.pending_real_timer_count
-      end
-    end
-  end
-end

data/lib/phronomy/engine/runtime/task_registry.rb

@@ -1,95 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  class Runtime
-    # Internal registry of active {Task} instances for a {Runtime}.
-    #
-    # Tracks every task that has been spawned but not yet completed so that
-    # {Runtime#shutdown} can drain them. Tasks that complete synchronously
-    # deregister themselves before the caller returns from {Runtime#spawn}.
-    # @api private
-    class TaskRegistry
-      def initialize
-        @mutex = Mutex.new
-        @tasks = []
-      end
-
-      # Adds +task+ unless it already completed synchronously.
-      # @api private
-      def register(task)
-        @mutex.synchronize { @tasks << task unless task.done? }
-      end
-
-      # Removes +task+ from the registry.
-      # @api private
-      def deregister(task)
-        @mutex.synchronize { @tasks.delete(task) }
-      end
-
-      # Waits for registered tasks until the absolute monotonic +deadline+.
-      # The registry is re-snapshotted because tasks may create follow-up tasks
-      # while Runtime shutdown is draining accepted work.
-      #
-      # @param deadline [Numeric] absolute Process::CLOCK_MONOTONIC value
-      # @return [Symbol] +:empty+ or +:timeout+
-      # @api private
-      def drain_until(deadline)
-        loop do
-          tasks = snapshot
-          return :empty if tasks.empty?
-
-          tasks.each do |task|
-            remaining = deadline - monotonic_now
-            return :timeout if remaining <= 0
-
-            begin
-              task.join(remaining)
-            rescue
-              # Some backends re-raise the task error from join. The task's
-              # ensure block still deregisters it, so continue the drain.
-              nil
-            end
-
-            return :timeout if task.alive? && monotonic_now >= deadline
-          end
-
-          return :empty if empty?
-          return :timeout if monotonic_now >= deadline
-        end
-      end
-
-      # Compatibility helper for callers that explicitly require an unbounded
-      # drain. Runtime#shutdown uses {#drain_until}.
-      # @api private
-      def drain
-        snapshot.each do |task|
-          task.join
-        rescue
-          nil
-        end
-      end
-
-      # @return [Boolean]
-      # @api private
-      def empty?
-        @mutex.synchronize { @tasks.empty? }
-      end
-
-      # @return [Integer]
-      # @api private
-      def size
-        @mutex.synchronize { @tasks.size }
-      end
-
-      private
-
-      def snapshot
-        @mutex.synchronize { @tasks.dup }
-      end
-
-      def monotonic_now
-        Process.clock_gettime(Process::CLOCK_MONOTONIC)
-      end
-    end
-  end
-end

data/lib/phronomy/engine/runtime/thread_scheduler.rb

@@ -1,30 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  class Runtime
-    # Thread-based scheduler: spawns each task in a new OS thread.
-    #
-    # This is the default scheduler used by {Runtime} in production.
-    # It delegates directly to {Task.spawn} with the default
-    # {Task::ThreadBackend}, preserving the pre-282 behaviour exactly.
-    # @api private
-    class ThreadScheduler < Scheduler
-      # Spawns +block+ as a new {Task} backed by a Thread.
-      #
-      # @param name   [String, nil]
-      # @param parent [Task, nil]
-      # @return [Task]
-      # @api private
-      def spawn(name:, parent:, &block)
-        Task.spawn(name: name, parent: parent, &block)
-      end
-
-      # Yields the current thread's time slice to other runnable threads.
-      # @return [void]
-      # @api private
-      def yield
-        Thread.pass
-      end
-    end
-  end
-end

data/lib/phronomy/engine/task/backend.rb

@@ -1,80 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  class Task
-    # Abstract base class for Task execution backends.
-    #
-    # A backend encapsulates the execution primitive (Thread, Fiber, etc.) and
-    # the lifecycle transitions it drives.  Concrete backends must implement all
-    # abstract methods.  The default concrete implementation is {ThreadBackend}.
-    #
-    # Backends receive a reference to the owning {Task} so they can call
-    # {Task#transition!} at the appropriate lifecycle points.
-    class Backend
-      # @param task  [Task] the owning Task (used for status callbacks)
-      # @param block [Proc] the work to execute
-      # @api private
-      def initialize(task:, &block)
-        @task = task
-        @block = block
-      end
-
-      # Blocks until the task completes and returns its value.
-      # Re-raises errors from the block.
-      # @return [Object]
-      # @raise [Exception]
-      # @api private
-      def wait_result
-        raise NotImplementedError, "#{self.class}#wait_result not implemented"
-      end
-
-      # Returns +true+ while execution is still ongoing.
-      # @return [Boolean]
-      # @api private
-      def alive?
-        raise NotImplementedError, "#{self.class}#alive? not implemented"
-      end
-
-      # Requests cancellation.
-      # Thread-based backends may use +Thread#raise+; cooperative backends
-      # should mark the task cancelled and rely on {Task.checkpoint!}.
-      # @return [self]
-      # @api private
-      def cancel!
-        raise NotImplementedError, "#{self.class}#cancel! not implemented"
-      end
-
-      # Joins the execution context with an optional timeout.
-      # Returns +nil+ when a non-nil +limit+ expires before completion,
-      # matching +Thread#join+ semantics.
-      # @param limit [Numeric, nil]
-      # @return [Object, nil]
-      # @api private
-      def join(limit = nil)
-        raise NotImplementedError, "#{self.class}#join not implemented"
-      end
-
-      # Returns the task's result value once it has reached a terminal state.
-      # Only valid to call after the task is done.
-      # Subclasses should override if they store the result.
-      # @return [Object, nil]
-      # @api private
-      def completed_value
-        nil
-      end
-
-      # Returns the exception raised by the task, or +nil+ on success/cancellation.
-      # Only valid to call after the task is done.
-      # Subclasses should override if they store errors.
-      # @return [Exception, nil]
-      # @api private
-      def completed_error
-        nil
-      end
-
-      private
-
-      attr_reader :task, :block
-    end
-  end
-end

data/lib/phronomy/engine/task/deferred_backend.rb

@@ -1,73 +0,0 @@
-# frozen_string_literal: true
-
-require "timeout"
-
-module Phronomy
-  class Task
-    # Backend for externally-completed Tasks.
-    #
-    # DeferredBackend never starts a thread.  The owner transitions it to a
-    # terminal state by calling Task#transition! and then #unblock.
-    # @api private
-    class DeferredBackend < Backend
-      def initialize(task:, &)
-        super
-        @done_queue = Queue.new
-        task.transition!(:running)
-      end
-
-      # Unblocks await/join after the task reaches a terminal state.
-      # @api private
-      def unblock(value, error)
-        @done_queue.push([value, error])
-      end
-
-      # Blocks until externally completed.
-      # @api private
-      def wait_result
-        scheduler = Thread.current.thread_variable_get(Task::SCHEDULER_KEY)
-        in_managed_fiber = !Fiber.respond_to?(:main) || Fiber.current != Fiber.main
-        if scheduler && in_managed_fiber && !@task.done?
-          scheduler.track_blocking_await
-          waiting_fiber = Fiber.current
-          @task.on_complete do |_value, _error|
-            scheduler.complete_blocking_await
-            scheduler.enqueue_fiber(-> { waiting_fiber.resume })
-          end
-          Fiber.yield(:cooperative_suspend)
-        end
-
-        value, error = @done_queue.pop
-        raise error if error
-
-        value
-      end
-
-      # Deferred tasks have no execution thread of their own.
-      # @api private
-      def alive?
-        !@task.done?
-      end
-
-      # Marks the task cancelled without interrupting external work.
-      # @api private
-      def cancel!
-        self
-      end
-
-      # Blocks until externally completed, with optional timeout.
-      # @api private
-      def join(limit = nil)
-        if limit.nil?
-          wait_result
-        else
-          begin
-            Timeout.timeout(limit) { wait_result }
-          rescue Timeout::Error
-            nil
-          end
-        end
-      end
-    end
-  end
-end