phronomy 0.7.0 → 0.7.1

data/lib/phronomy/concurrency_gate.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+module Phronomy
+  # A counting semaphore that enforces a concurrency cap across a named
+  # resource category (e.g. agent tasks, tool tasks, LLM calls).
+  #
+  # When +max_concurrent+ is +nil+ the gate is a no-op and all callers
+  # pass through immediately without acquiring a slot.
+  #
+  # Backpressure behaviour when the gate is full is controlled by the
+  # +on_full:+ keyword:
+  #   +:reject+  — raise {Phronomy::BackpressureError} immediately
+  #   +:wait+    — block the calling fiber/thread until a slot is free
+  #   +:timeout+ — like +:wait+ but raises {Phronomy::BackpressureError}
+  #               after +timeout:+ seconds if no slot becomes available
+  #
+  # @example
+  #   gate = Phronomy::ConcurrencyGate.new(max_concurrent: 5, name: :agent)
+  #   gate.acquire(on_full: :reject) do
+  #     run_agent_task
+  #   end
+  class ConcurrencyGate
+    # @param max_concurrent [Integer, nil] concurrency cap; nil = unlimited
+    # @param name [Symbol, String, nil] human-readable label used in error messages
+    # @api private
+    def initialize(max_concurrent:, name: nil)
+      @max = max_concurrent
+      @name = name
+      @mutex = Mutex.new
+      @cond = ConditionVariable.new
+      @count = 0
+    end
+
+    # Returns the configured cap (or nil when unlimited).
+    attr_reader :max
+
+    # Returns the name label.
+    attr_reader :name
+
+    # Returns the number of slots currently in use.
+    def current_count
+      @mutex.synchronize { @count }
+    end
+
+    # Acquires a slot, executes +block+, then releases the slot.
+    # When the gate is unlimited (max is nil) the block runs directly.
+    #
+    # @param on_full [:reject, :wait, :timeout] backpressure strategy
+    # @param timeout [Numeric, nil] seconds before +:timeout+ gives up
+    # @yield
+    # @return block return value
+    # @raise [Phronomy::BackpressureError] when +:reject+ or +:timeout+ fires
+    # @api private
+    def acquire(on_full: :wait, timeout: nil, &block)
+      return block.call if @max.nil?
+
+      _acquire_slot(on_full: on_full, timeout: timeout)
+      begin
+        block.call
+      ensure
+        _release_slot
+      end
+    end
+
+    private
+
+    def _acquire_slot(on_full:, timeout:)
+      scheduler = Phronomy::Runtime::Scheduler.current
+      if scheduler
+        _acquire_slot_coop(scheduler, on_full: on_full, timeout: timeout)
+      else
+        _acquire_slot_threaded(on_full: on_full, timeout: timeout)
+      end
+    end
+
+    def _acquire_slot_coop(scheduler, on_full:, timeout:)
+      # In cooperative mode all tasks run on the same thread, so no mutex needed.
+      deadline = timeout ? (scheduler.virtual_time + timeout) : nil
+      @coop_signal ||= scheduler.new_signal
+
+      loop do
+        if @count < @max
+          @count += 1
+          return
+        end
+
+        case on_full
+        when :reject
+          raise Phronomy::BackpressureError,
+            "ConcurrencyGate[#{@name}] at capacity (#{@max}); " \
+            "increase max_concurrent_#{@name}_tasks or retry later"
+        when :timeout
+          if deadline && scheduler.virtual_time >= deadline
+            raise Phronomy::BackpressureError,
+              "ConcurrencyGate[#{@name}] timed out waiting for a free slot (cap: #{@max})"
+          end
+          scheduler.wait_for_signal(@coop_signal)
+          if deadline && scheduler.virtual_time >= deadline
+            raise Phronomy::BackpressureError,
+              "ConcurrencyGate[#{@name}] timed out waiting for a free slot (cap: #{@max})"
+          end
+        else # :wait
+          scheduler.wait_for_signal(@coop_signal)
+        end
+      end
+    end
+
+    def _acquire_slot_threaded(on_full:, timeout:)
+      deadline = timeout ? (Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout) : nil
+
+      @mutex.synchronize do
+        loop do
+          if @count < @max
+            @count += 1
+            return
+          end
+
+          case on_full
+          when :reject
+            raise Phronomy::BackpressureError,
+              "ConcurrencyGate[#{@name}] at capacity (#{@max}); " \
+              "increase max_concurrent_#{@name}_tasks or retry later"
+          when :timeout
+            remaining = deadline ? (deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)) : nil
+            if remaining && remaining <= 0
+              raise Phronomy::BackpressureError,
+                "ConcurrencyGate[#{@name}] timed out waiting for a free slot (cap: #{@max})"
+            end
+            @cond.wait(@mutex, remaining || nil)
+            # re-check deadline after wakeup
+            if deadline && Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
+              raise Phronomy::BackpressureError,
+                "ConcurrencyGate[#{@name}] timed out waiting for a free slot (cap: #{@max})"
+            end
+          else # :wait
+            @cond.wait(@mutex)
+          end
+        end
+      end
+    end
+
+    def _release_slot
+      scheduler = Phronomy::Runtime::Scheduler.current
+      if scheduler && @coop_signal
+        @count -= 1
+        scheduler.raise_signal(@coop_signal)
+      else
+        @mutex.synchronize do
+          @count -= 1
+          @cond.signal
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/configuration.rb

@@ -61,12 +61,154 @@ module Phronomy
     #   Phronomy.configure { |c| c.state_store = Phronomy::StateStore::InMemory.new }
     attr_accessor :state_store
 
+    # Maximum byte length of a tool result returned to the LLM.
+    # When a tool returns a String longer than this limit, the string is truncated
+    # and a warning is logged.  Set to +nil+ (default) to disable truncation.
+    # @example
+    #   Phronomy.configure { |c| c.tool_result_max_size = 8192 }
+    attr_accessor :tool_result_max_size
+
+    # LLM adapter used by Agent::Base to perform LLM calls.
+    # Must be an instance of a class that inherits from
+    # {Phronomy::LLMAdapter::Base}.  Defaults to
+    # {Phronomy::LLMAdapter::RubyLLM} which delegates to +chat.ask+ via
+    # {BlockingAdapterPool}.
+    # Set to a custom adapter to swap in an alternative LLM client without
+    # changing any agent code.
+    # @example
+    #   Phronomy.configure { |c| c.llm_adapter = MyAsyncLLMAdapter.new }
+    attr_accessor :llm_adapter
+
+    # Default backpressure strategy for {BlockingAdapterPool#submit} when the
+    # queue is full.  One of +:wait+ (block until a slot is available),
+    # +:raise+ (raise {Phronomy::BackpressureError}), or +:timeout+ (raise
+    # {Phronomy::TimeoutError} after +backpressure_timeout+ seconds).
+    # @return [:wait, :raise, :timeout]
+    attr_accessor :backpressure
+
+    # Seconds to wait before raising {Phronomy::TimeoutError} when
+    # +backpressure+ is +:timeout+.
+    # @return [Numeric, nil]
+    attr_accessor :backpressure_timeout
+
+    # Warn when an event spends longer than this many seconds waiting in the
+    # EventLoop queue before being dispatched (starvation detection).
+    # Set to +nil+ to disable the warning.
+    # @return [Numeric, nil]
+    attr_accessor :event_loop_starvation_threshold_seconds
+
+    # Warn when processing a single event on the EventLoop thread takes longer
+    # than this many seconds (long-running task / blocking-on-loop detection).
+    # Set to +nil+ to disable the warning.
+    # @return [Numeric, nil]
+    attr_accessor :event_loop_dispatch_threshold_seconds
+
+    # When true, enables all blocking operation diagnostics (Issue #279).
+    # Equivalent to setting all diagnostic thresholds to their defaults.
+    # @return [Boolean]
+    attr_accessor :scheduler_debug
+
+    # Wall-clock threshold (milliseconds) after which a task that has not
+    # yielded the scheduler emits a warning log.  nil disables the check.
+    # @return [Float, nil]
+    attr_accessor :blocking_detect_threshold_ms
+
+    # Maximum number of concurrent agent tasks (invoke_async calls in-flight).
+    # nil = unlimited (default).  When at capacity, behaviour is controlled by
+    # +backpressure+ (:wait, :raise/:reject, :timeout).
+    # @return [Integer, nil]
+    attr_accessor :max_concurrent_agent_tasks
+
+    # Maximum number of concurrent tool tasks (parallel tool calls in-flight).
+    # nil = unlimited (default).
+    # @return [Integer, nil]
+    attr_accessor :max_concurrent_tool_tasks
+
+    # Maximum number of concurrent workflow tasks.
+    # nil = unlimited (default).
+    # @return [Integer, nil]
+    attr_accessor :max_concurrent_workflow_tasks
+
+    # Maximum number of concurrent LLM calls in-flight.
+    # nil = unlimited (default).
+    # @return [Integer, nil]
+    attr_accessor :max_concurrent_llm_calls
+
+    # Upper bound on the number of streaming token chunks that may be buffered
+    # in the {AsyncQueue} used by {Agent#stream} before the LLM producer is
+    # throttled.  When nil (default), the queue is unbounded.
+    # @return [Integer, nil]
+    attr_accessor :stream_queue_max_size
+
+    # Maximum number of concurrent RAG knowledge-source fetches in-flight.
+    # nil = unlimited (default).
+    # @return [Integer, nil]
+    attr_accessor :max_concurrent_rag_fetches
+
+    # Maximum number of concurrent vector-store searches in-flight.
+    # nil = unlimited (default).
+    # @return [Integer, nil]
+    attr_accessor :max_concurrent_vector_searches
+
+    # Scheduler starvation threshold (milliseconds).
+    # When a task waits more than this many milliseconds after calling
+    # +runtime.yield+ before being resumed, the wait is counted as a starvation
+    # event.  Used by the fairness regression test and by the
+    # +tasks_waiting_over_threshold+ metric on {Phronomy::Runtime}.
+    # Default: 50ms.
+    # @return [Numeric]
+    attr_accessor :starvation_threshold_ms
+
+    # Scheduler backend to use for new {Phronomy::Runtime} instances.
+    #
+    # | Value | Scheduler | Typical use |
+    # |-------|-----------|-------------|
+    # | +:thread+ | {Runtime::ThreadScheduler} | **Default** — production-ready; one OS thread per task |
+    # | +:immediate+ | {Runtime::FakeScheduler} | Tests — tasks run synchronously, no extra threads |
+    # | +:fiber+ | {Runtime::DeterministicScheduler} (autorun) | **EXPERIMENTAL** — Fiber-based cooperative scheduler; do not use as production default |
+    # | +:cooperative+ | {Runtime::FakeScheduler} | **Deprecated** — alias for +:immediate+; do not use in new code |
+    #
+    # The default is +:thread+. The +:fiber+ backend remains experimental and opt-in;
+    # it will not become the default until integration test coverage is production grade
+    # and virtual-time/timeout semantics are fully resolved (see Issues #350, #347, #348).
+    #
+    # When this setting is changed, the change only takes effect on the NEXT
+    # call to {Runtime.instance} that auto-creates a new instance (i.e. after the
+    # previous instance has been replaced or reset).  To replace the current
+    # instance immediately call +Phronomy::Runtime.instance = nil+ first.
+    #
+    # @return [:thread, :immediate, :fiber]
+    attr_accessor :runtime_backend
+
+    # When +true+, calling {Agent#invoke} from inside a scheduler task
+    # raises {SchedulerReentrancyError}.  When +false+ (default), a warning
+    # is logged instead so that existing callers have time to migrate.
+    # @return [Boolean]
+    attr_accessor :strict_runtime_guards
+
     def initialize
       @recursion_limit = 25
       @tracer = Phronomy::Tracing::NullTracer.new
       @trace_pii = false
       @event_loop = false
       @event_loop_stop_grace_seconds = 5
+      @llm_adapter = Phronomy::LLMAdapter::RubyLLM.new
+      @backpressure = :wait
+      @backpressure_timeout = nil
+      @event_loop_starvation_threshold_seconds = nil
+      @event_loop_dispatch_threshold_seconds = nil
+      @scheduler_debug = false
+      @blocking_detect_threshold_ms = nil
+      @max_concurrent_agent_tasks = nil
+      @max_concurrent_tool_tasks = nil
+      @max_concurrent_workflow_tasks = nil
+      @max_concurrent_llm_calls = nil
+      @stream_queue_max_size = nil
+      @max_concurrent_rag_fetches = nil
+      @max_concurrent_vector_searches = nil
+      @starvation_threshold_ms = 50
+      @runtime_backend = :thread
+      @strict_runtime_guards = false
     end
   end
 end

data/lib/phronomy/deadline.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Phronomy
+  # A point in time used as an upper bound for an operation.
+  #
+  # Uses the monotonic clock (+Process::CLOCK_MONOTONIC+) internally to avoid
+  # skew from NTP adjustments or DST transitions.
+  #
+  # @example Create a 30-second deadline and check remaining time
+  #   deadline = Phronomy::Deadline.in(30)
+  #   sleep 1
+  #   deadline.remaining_seconds   # => ~29.0
+  #   deadline.expired?            # => false
+  class Deadline
+    # Creates a deadline that expires +seconds+ from now.
+    #
+    # @param seconds [Numeric] seconds from now until expiry
+    # @return [Deadline]
+    # @api private
+    def self.in(seconds)
+      new(Process.clock_gettime(Process::CLOCK_MONOTONIC) + seconds)
+    end
+
+    # @param monotonic_at [Float] absolute monotonic timestamp of expiry
+    # @api private
+    def initialize(monotonic_at)
+      @monotonic_at = monotonic_at
+    end
+
+    # Returns +true+ when the deadline has passed.
+    # @return [Boolean]
+    # @api private
+    def expired?
+      Process.clock_gettime(Process::CLOCK_MONOTONIC) >= @monotonic_at
+    end
+
+    # Seconds remaining until expiry.  Returns 0 when already expired.
+    # @return [Float]
+    # @api private
+    def remaining_seconds
+      remaining = @monotonic_at - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      [remaining, 0.0].max
+    end
+
+    # Attaches this deadline to a {CancellationToken} by cancelling the token
+    # when the deadline expires.  Uses the Runtime timer queue (a single
+    # background thread shared by all deadlines) instead of spawning one thread
+    # per deadline.
+    #
+    # @param token [CancellationToken]
+    # @param timer_queue [Runtime::TimerQueue, nil] queue to register with;
+    #   defaults to +Phronomy::Runtime.instance.timer_queue+
+    # @return [self]
+    # @api private
+    def attach_to(token, timer_queue: Phronomy::Runtime.instance.timer_queue)
+      seconds = remaining_seconds
+      return self if seconds <= 0
+
+      timer_queue.schedule(seconds: seconds) { token.cancel! }
+      self
+    end
+  end
+end

data/lib/phronomy/diagnostics.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Phronomy
+  # Developer-facing diagnostics for blocking operation detection (Issue #279).
+  #
+  # Provides debug dump utilities that can be called from an IRB / Rails console
+  # or in test helpers to inspect the current state of the Runtime.
+  #
+  # @example Enable diagnostics and print a dump
+  #   Phronomy.configure { |c| c.scheduler_debug = true }
+  #   Phronomy::Diagnostics.dump
+  module Diagnostics
+    # Prints a formatted summary of the current Runtime state to +$stderr+
+    # (or the supplied IO).
+    #
+    # Includes:
+    # - BlockingAdapterPool: active workers, queue depth, abandoned count
+    # - EventLoop: last / max / average lag in milliseconds
+    #
+    # @param out [IO] output destination (default: $stderr)
+    # @return [void]
+    # @api public
+    def self.dump(out: $stderr)
+      snap = Phronomy::Metrics.snapshot
+
+      out.puts "[Phronomy::Diagnostics] Runtime state dump"
+      out.puts "  BlockingAdapterPool:"
+      out.puts "    pool_size       : #{snap[:blocking_pool_size]}"
+      out.puts "    active_count    : #{snap[:blocking_pool_active]}"
+      out.puts "    queue_depth     : #{snap[:blocking_pool_queue_length]}"
+      out.puts "    abandoned_total : #{snap[:blocking_pool_abandoned_total]}"
+      out.puts "  EventLoop:"
+      out.puts "    last_lag_ms     : #{snap[:event_loop_lag_last_ms]}"
+      out.puts "    max_lag_ms      : #{snap[:event_loop_lag_max_ms]}"
+      out.puts "    average_lag_ms  : #{snap[:event_loop_lag_average_ms]}"
+    end
+
+    # Returns the diagnostics state as a plain Hash (useful for JSON export).
+    #
+    # @return [Hash]
+    # @api public
+    def self.snapshot
+      Phronomy::Metrics.snapshot
+    end
+
+    # Raises an error if +invoke+ (blocking) is called from inside an EventLoop
+    # action, preventing accidental scheduler stalls.
+    #
+    # Called by Agent::Base#invoke and Workflow#invoke before executing.
+    #
+    # @raise [Phronomy::SchedulerReentrancyError] when called from EventLoop thread
+    # @return [void]
+    # @api private
+    def self.assert_not_in_event_loop!
+      return unless Phronomy::EventLoop.current?
+
+      raise Phronomy::SchedulerReentrancyError,
+        "Blocking invoke called from inside an EventLoop action. " \
+        "Use invoke_async instead."
+    end
+  end
+end

data/lib/phronomy/embeddings/base.rb

@@ -17,6 +17,23 @@ module Phronomy
         cancellation_token&.raise_if_cancelled!
         raise NotImplementedError, "#{self.class}#embed is not implemented"
       end
+
+      # Submits an {#embed} call to {BlockingAdapterPool} and returns a
+      # {BlockingAdapterPool::PendingOperation}.
+      #
+      # @param text               [String]
+      # @param cancellation_token [Phronomy::CancellationToken, nil]
+      # @param timeout            [Numeric, nil] seconds before the operation is abandoned
+      # @return [BlockingAdapterPool::PendingOperation]
+      # @api public
+      def embed_async(text, cancellation_token = nil, timeout: nil)
+        Phronomy::Runtime.instance.blocking_io.submit(
+          timeout: timeout,
+          cancellation_token: cancellation_token
+        ) do
+          embed(text, cancellation_token)
+        end
+      end
     end
   end
 end

data/lib/phronomy/eval/runner.rb

@@ -32,25 +32,25 @@ module Phronomy
         cases = dataset.to_a
         return cases.map { |eval_case| run_one(eval_case, callable) } if concurrency <= 1
 
-        # Run cases in slices of +concurrency+ threads. Each slice is joined
-        # before the next starts, bounding peak thread count to +concurrency+.
-        # Writing to pre-allocated slots (one per thread) is safe because each
-        # thread writes to a unique index and all threads in a slice are joined
+        # Run cases in slices of +concurrency+ tasks. Each slice is joined
+        # before the next starts, bounding peak task count to +concurrency+.
+        # Writing to pre-allocated slots (one per task) is safe because each
+        # task writes to a unique index and all tasks in a slice are joined
         # before the next slice begins.
-        # Exceptions in worker threads are collected and re-raised after all
-        # threads in the slice are joined, preventing orphaned threads.
+        # Exceptions in worker tasks are collected and re-raised after all
+        # tasks in the slice are joined, preventing orphaned tasks.
         results = Array.new(cases.length)
         cases.each_with_index.each_slice(concurrency) do |batch|
           errors = []
           errors_mu = Mutex.new
-          threads = batch.map do |eval_case, i|
-            Thread.new do
+          tasks = batch.map do |eval_case, i|
+            Phronomy::Runtime.instance.spawn(name: "eval-case-#{i}") do
               results[i] = run_one(eval_case, callable)
             rescue => e
               errors_mu.synchronize { errors << e }
             end
           end
-          threads.each(&:join)
+          tasks.each(&:join)
           raise errors.first if errors.any?
         end
         results