phronomy 0.16.0 → 0.18.0

data/lib/phronomy/engine/task.rb

@@ -1,335 +1,194 @@
 # frozen_string_literal: true
 
-require_relative "task/backend"
-require_relative "task/thread_backend"
-require_relative "task/immediate_backend"
-require_relative "task/fiber_backend"
-require_relative "task/mapped_backend"
-require_relative "task/deferred_backend"
-
 module Phronomy
-  # A single unit of concurrent work.
-  #
-  # Decouples task semantics from the underlying execution primitive via a
-  # pluggable {Backend}.  The default backend is {ThreadBackend}; a cooperative
-  # or test-double backend can be substituted via {.default_backend_class=} or
-  # by passing +backend_class:+ to {.spawn}.
-  #
-  # +Task.spawn+ is an **internal API** used by schedulers and the framework
-  # itself.  Application code and framework components should use
-  # +Runtime.instance.spawn+ instead, which routes through the configured
-  # scheduler and respects the concurrency model.
+  # A thread-free asynchronous completion handle.
   #
-  # @example Basic usage (framework/test code only — prefer Runtime.instance.spawn in app code)
-  #   task = Phronomy::Task.spawn { expensive_io() }
-  #   result = task.wait_result   # blocks until done, re-raises errors
-  #
-  # @example Cancel a running task
-  #   task = Phronomy::Task.spawn { loop { Phronomy::Task.checkpoint! } }
-  #   task.cancel!
-  #
-  # @example Task tree — cancel parent cancels children
-  #   parent = Phronomy::Task.spawn { sleep 10 }
-  #   child  = Phronomy::Task.spawn(parent: parent) { sleep 10 }
-  #   parent.cancel!   # child is also cancelled
+  # Task no longer executes work. Execution belongs to EventLoop/FSMSession or
+  # OffloadPool. Task only represents completion, failure, cancellation,
+  # callbacks and a blocking wait for external callers.
   class Task
-    # Valid task lifecycle states.
-    STATES = %i[pending running completed failed cancelled].freeze
-
-    # Returns the process-wide default backend class.
-    # Defaults to {ThreadBackend}.
-    # Override in tests or to enable a cooperative scheduler backend.
-    # @return [Class<Backend>]
-    # @api private
-    def self.default_backend_class
-      @default_backend_class || ThreadBackend
-    end
-
-    # Sets the process-wide default backend class.
-    # @param klass [Class<Backend>]
-    # @api private
-    def self.default_backend_class=(klass)
-      @default_backend_class = klass
-    end
-
-    # Returns the {Task} currently executing on this thread, or +nil+.
-    # Returns +nil+ when called from outside a task-managed execution context.
-    # @return [Task, nil]
-    # @api private
-    def self.current
-      Thread.current[:phronomy_current_task]
-    end
-
-    # Returns the monotonic clock value (ms) when the current task last recorded
-    # a yield (or when the task started), or +nil+ when not inside a task context.
-    # Used by {Runtime#yield} for CPU-bound detection without placing
-    # +Thread.current+ in files outside the allowlist.
-    # @return [Integer, nil]
-    # @api private
-    def self.current_cpu_slice_start_ms
-      Thread.current[:phronomy_task_cpu_slice_start_ms]
-    end
-
-    # Resets the CPU slice start clock for the current task to +now+.
-    # Call this immediately after the cooperative yield has been performed so
-    # that the next yield correctly measures only the time since the last yield.
-    # @api private
-    def self.record_yield!
-      Thread.current[:phronomy_task_cpu_slice_start_ms] =
-        Process.clock_gettime(Process::CLOCK_MONOTONIC, :millisecond)
-    end
-
-    # Returns and increments a per-thread yield-if-needed counter.
-    # Used by {Runtime#yield_if_needed} so that the counter is thread-local
-    # without putting +Thread.current+ in runtime.rb (which is outside the
-    # Thread.current allowlist).
-    # @return [Integer] the new counter value
-    # @api private
-    def self.increment_yield_counter!
-      count = (Thread.current[:phronomy_yield_if_needed_counter] || 0) + 1
-      Thread.current[:phronomy_yield_if_needed_counter] = count
-      count
-    end
-
-    # Cooperative cancellation checkpoint.
-    #
-    # Raises {CancellationError} if the current task's status is +:cancelled+.
-    # On {ThreadBackend}, cancellation is delivered via +Thread#raise+ so this
-    # is a no-op in practice; on future cooperative backends this will be the
-    # primary cancellation mechanism.
-    #
-    # Safe to call from outside a task context (no-op when no current task).
-    # @return [void]
-    # @raise [CancellationError] if the current task has been cancelled
-    # @api private
-    def self.checkpoint!
-      ct = current
-      return unless ct
-
-      raise CancellationError, "Task cancelled" if ct.status == :cancelled
-    end
+    STATES = %i[pending completed failed cancelled].freeze
+    TERMINAL_STATES = %i[completed failed cancelled].freeze
+    private_constant :TERMINAL_STATES
 
-    # Spawns a new task executing +block+ concurrently.
-    #
-    # @param name          [String, nil]    optional human-readable label
-    # @param parent        [Task, nil]      parent task; cancelling the parent
-    #   also cancels this task (default: currently running task)
-    # @param backend_class [Class<Backend>] backend to use
-    # @yieldreturn [Object] the task result
-    # @return [Task]
-    # @api private
-    def self.spawn(name: nil, parent: current, backend_class: default_backend_class, &block)
-      new(name: name, parent: parent, backend_class: backend_class, &block)
-    end
-
-    # Creates a task whose lifecycle is completed externally.
-    # @param name [String, nil]
-    # @param parent [Task, nil]
-    # @return [Task]
-    # @api private
-    def self.deferred(name: nil, parent: current)
-      new(name: name, parent: parent, backend_class: DeferredBackend) {}
+    def self.deferred(name: nil, parent: nil)
+      new(name: name, parent: parent)
     end
 
-    # @return [String, nil] optional human-readable label
-    attr_reader :name
+    attr_reader :name, :parent
 
-    # @return [Task, nil] parent task in the task tree, if any
-    attr_reader :parent
-
-    # @return [Backend] the execution backend for this task
-    # @api private
-    attr_reader :backend
-
-    # @param name          [String, nil]
-    # @param parent        [Task, nil]
-    # @param backend_class [Class<Backend>]
-    # @api private use {.spawn} instead
-    def initialize(name: nil, parent: nil, backend_class: self.class.default_backend_class, &block)
+    def initialize(name: nil, parent: nil)
       @name = name
       @parent = parent
       @status = :pending
+      @value = nil
+      @error = nil
       @mutex = Mutex.new
+      @cond = ConditionVariable.new
       @children = []
       @on_complete_callbacks = []
-      @completed_value = nil
-      @completed_error = nil
       parent&.register_child(self)
-      @backend = backend_class.new(task: self, &block)
     end
 
-    # Returns the current lifecycle state.
-    # @return [Symbol] one of {STATES}
-    # @api private
     def status
       @mutex.synchronize { @status }
     end
 
-    # Blocks until the task completes and returns its value.
-    # Re-raises any exception raised inside the block.
-    #
-    # @return [Object] the result produced by the block
-    # @raise [Exception] if the block raised an error
-    # @api private
-    def wait_result
-      @backend.wait_result
+    def done?
+      @mutex.synchronize { TERMINAL_STATES.include?(@status) }
     end
 
-    # Registers a callback to be invoked when the task reaches a terminal state
-    # (+:completed+, +:failed+, or +:cancelled+).
-    #
-    # The callback receives two arguments: +value+ (the task's return value,
-    # or +nil+) and +error+ (the exception, or +nil+).  These are provided
-    # directly so the callback does not need to call +task.wait_result+, which would
-    # risk a self-join error when the callback runs inside the task's own thread.
-    #
-    # If the task is already done when this method is called, the callback is
-    # invoked immediately (synchronously, on the calling thread).
+    def alive?
+      !done?
+    end
+
+    # Blocks the calling thread until settlement. EventLoop is never allowed to
+    # wait for a Task; it must continue through explicit events instead.
+    def wait_result(timeout: nil)
+      if Phronomy::Runtime.in_event_loop_context? && !done?
+        raise Phronomy::EventLoopReentrancyError,
+          "Task#wait_result cannot block the EventLoop thread; continue via an event"
+      end
+
+      deadline = timeout && monotonic_now + timeout.to_f
+      value, error = @mutex.synchronize do
+        until TERMINAL_STATES.include?(@status)
+          if deadline
+            remaining = deadline - monotonic_now
+            if remaining <= 0
+              raise Phronomy::TimeoutError,
+                "timed out waiting for Task #{@name || "(unnamed)"}"
+            end
+            @cond.wait(@mutex, remaining)
+          else
+            @cond.wait(@mutex)
+          end
+        end
+        [@value, @error]
+      end
+
+      raise error if error
+      value
+    end
+
+    # Compatibility wait that does not re-raise the task error.
+    # Returns self when settled, nil on timeout.
+    def join(limit = nil)
+      if Phronomy::Runtime.in_event_loop_context? && !done?
+        raise Phronomy::EventLoopReentrancyError,
+          "Task#join cannot block the EventLoop thread; continue via an event"
+      end
+
+      deadline = limit && monotonic_now + limit.to_f
+      @mutex.synchronize do
+        until TERMINAL_STATES.include?(@status)
+          if deadline
+            remaining = deadline - monotonic_now
+            return nil if remaining <= 0
+            @cond.wait(@mutex, remaining)
+          else
+            @cond.wait(@mutex)
+          end
+        end
+      end
+      self
+    end
+
+    # Registers an independent completion notification.
     #
-    # @yield [value, error] called when the task finishes
-    # @return [self]
-    # @api private
+    # A callback failure is logged and does not suppress delivery to other
+    # completion callbacks or change the Task's already-settled result.
     def on_complete(&callback)
-      fire_now = false
+      raise ArgumentError, "on_complete requires a block" unless callback
+
       fire_args = nil
       @mutex.synchronize do
-        # Check @status directly to avoid re-entering the mutex (done? calls
-        # status, which also takes @mutex).
-        if %i[completed failed cancelled].include?(@status)
-          fire_now = true
-          fire_args = [@completed_value, @completed_error]
+        if TERMINAL_STATES.include?(@status)
+          fire_args = [@value, @error]
         else
           @on_complete_callbacks << callback
         end
       end
-      callback.call(*fire_args) if fire_now
+      deliver_completion_callback(callback, *fire_args) if fire_args
+      self
+    end
+
+    def complete(value = nil)
+      settle!(:completed, value: value)
+    end
+
+    def fail(error)
+      raise ArgumentError, "error is required" unless error
+      settle!(:failed, error: error)
+    end
+
+    def cancel!(error = Phronomy::CancellationError.new("Task cancelled"))
+      changed = settle!(:cancelled, error: error)
+      if changed
+        children = @mutex.synchronize { @children.dup }
+        children.each(&:cancel!)
+      end
       self
     end
 
-    # Returns a new {Task} whose completed value is the result of applying
-    # +block+ to this task's completed value.
-    #
-    # If this task fails or is cancelled, the mapped task also fails/is
-    # cancelled with the same error.  The block is never called in error cases.
-    #
-    # The transformation runs from the source Task's completion callback.
-    # It is a generic value-composition API; Workflow entry actions do not await
-    # either the source Task or the mapped Task.
-    #
-    # @example Transforming an Agent result outside a Workflow entry action
-    #   output_task = agent.invoke_async("hello").map { |result| result[:output] }
-    #
-    # @yield  [value] the completed value of this task
-    # @yieldreturn [Object] the value for the mapped task
-    # @return [Task] a new task that completes when this task does
-    # @api public
     def map(&block)
-      # MappedBackend drives the task lifecycle entirely via on_complete;
-      # it never spawns a thread of its own.
-      mapped = self.class.spawn(
-        name: "#{@name}-mapped",
-        parent: @parent,
-        backend_class: MappedBackend
-      ) {}
+      raise ArgumentError, "map requires a block" unless block
 
+      mapped = self.class.deferred(name: "#{@name}-mapped", parent: @parent)
       on_complete do |value, error|
-        mapped_value = nil
-        mapped_error = error
-        unless error
-          begin
-            mapped_value = block.call(value)
-          rescue => e
-            mapped_error = e
-          end
+        if error
+          mapped.fail(error)
+          next
         end
-        # Unblock mapped.wait_result / mapped.join before the terminal transition.
-        # on_complete callbacks may resume a waiting Fiber immediately; the
-        # queue must already contain the result at that point.
-        mapped.backend.unblock(mapped_value, mapped_error)
-        if mapped_error
-          mapped.transition!(:failed, error: mapped_error)
-        else
-          mapped.transition!(:completed, value: mapped_value)
+
+        begin
+          mapped.complete(block.call(value))
+        rescue => mapped_error
+          mapped.fail(mapped_error)
         end
       end
       mapped
     end
 
-    # Returns +true+ once the task has finished (success, error, or cancellation).
-    # @return [Boolean]
-    # @api private
-    def done?
-      %i[completed failed cancelled].include?(status)
-    end
+    protected
 
-    # Requests cancellation.  Propagates to all registered child tasks.
-    # Sets status to :cancelled immediately so that even tasks that have not
-    # started executing yet are correctly marked as cancelled after join.
-    # Passes a CancellationError to on_complete callbacks so callers do not
-    # need to call await to discover the error.
-    # @return [self]
-    # @api private
-    def cancel!
-      transition!(:cancelled, error: CancellationError.new("Task cancelled"))
-      # @backend may be nil if cancel! is called while ImmediateBackend is still
-      # initializing (the block runs synchronously inside .new, so register_child
-      # fires before @backend is assigned).  Safe-navigate to avoid NoMethodError.
-      @backend&.cancel!
-      children = @mutex.synchronize { @children.dup }
-      children.each(&:cancel!)
-      self
+    def register_child(child)
+      @mutex.synchronize { @children << child }
     end
 
-    # Joins the underlying execution context, optionally with a timeout.
-    # Returns +nil+ when the timeout expires before completion.
-    #
-    # @param limit [Numeric, nil] seconds to wait; nil waits indefinitely
-    # @return [Object, nil]
-    # @api private
-    def join(limit = nil)
-      @backend.join(limit)
-    end
+    private
 
-    # Returns +true+ while the task's block is still executing.
-    # @return [Boolean]
-    # @api private
-    def alive?
-      @backend.alive?
-    end
-
-    # Updates the task lifecycle state.
-    # Called by backends during execution transitions.
-    # Terminal states (completed/failed/cancelled) are never overwritten.
-    # When a terminal state is reached, fires on_complete callbacks (outside
-    # the mutex) passing the result value and error directly.
-    #
-    # @param new_status [Symbol]
-    # @param value      [Object, nil]    task return value (terminal states only)
-    # @param error      [Exception, nil] exception raised by the block, if any
-    # @api private
-    def transition!(new_status, value: nil, error: nil)
+    def settle!(new_status, value: nil, error: nil)
       callbacks = nil
-      @mutex.synchronize do
-        # Check @status directly (not via #done?) to avoid re-entering the mutex.
-        return if %i[completed failed cancelled].include?(@status)
+      changed = @mutex.synchronize do
+        next false if TERMINAL_STATES.include?(@status)
 
         @status = new_status
-        if %i[completed failed cancelled].include?(new_status)
-          @completed_value = value
-          @completed_error = error
-          callbacks = @on_complete_callbacks.dup
-          @on_complete_callbacks.clear
+        @value = value
+        @error = error
+        callbacks = @on_complete_callbacks.dup
+        @on_complete_callbacks.clear
+        @cond.broadcast
+        true
+      end
+      if changed
+        callbacks.each do |callback|
+          deliver_completion_callback(callback, value, error)
         end
       end
-      callbacks&.each { |cb| cb.call(value, error) }
+      changed
     end
 
-    # Registers +child+ as a child task for cancellation propagation.
-    # Called automatically during child task initialization.
-    # @param child [Task]
-    # @api private
-    def register_child(child)
-      @mutex.synchronize { @children << child }
+    def deliver_completion_callback(callback, value, error)
+      callback.call(value, error)
+    rescue => callback_error
+      Phronomy.configuration.logger&.error do
+        "[Task] on_complete callback raised #{callback_error.class}: #{callback_error.message}"
+      end
+    end
+
+    def monotonic_now
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
     end
   end
 end

data/lib/phronomy/llm_adapter/base.rb

@@ -6,11 +6,11 @@ module Phronomy
     #
     # Subclasses must implement {#complete} and {#stream}. The adapter or the
     # underlying provider client owns transport timeout, retry, backoff, and
-    # rate-limit behavior. Phronomy only supplies cooperative cancellation and
-    # isolates blocking calls in {BlockingAdapterPool}.
+    # rate-limit behavior. Phronomy supplies cooperative cancellation and
+    # isolates synchronous provider calls in {OffloadPool}.
     #
     # The agent pipeline calls {#complete_async} / {#stream_async} which wrap
-    # those methods in a {BlockingAdapterPool} submission.
+    # those methods in an {OffloadPool} submission.
     class Base
       # Performs a blocking (non-streaming) LLM completion.
       # Implementors must call +chat.ask(message)+ (or equivalent) and
@@ -41,8 +41,8 @@ module Phronomy
         raise NotImplementedError, "#{self.class}#stream is not implemented"
       end
 
-      # Submits a non-streaming LLM call to {BlockingAdapterPool} and returns
-      # a {BlockingAdapterPool::PendingOperation}.
+      # Submits a non-streaming LLM call to {OffloadPool} and returns
+      # an {OffloadPool::PendingOperation}.
       #
       # Transport timeout and retry remain the responsibility of the adapter or
       # provider client; Phronomy does not attach an additional operation timeout.
@@ -50,20 +50,20 @@ module Phronomy
       # @param chat    [Object] configured chat session
       # @param message [String] user message
       # @param config  [Hash] invocation config
-      # @param pool    [BlockingAdapterPool] pool to submit to
-      # @return [BlockingAdapterPool::PendingOperation]
+      # @param pool    [OffloadPool] pool to submit to
+      # @return [OffloadPool::PendingOperation]
       # @api private
       def complete_async(chat, message, config: {}, pool: default_pool)
         token = config[:cancellation_token]
-        pool.submit(cancellation_token: token) do
+        pool.submit(cancellation_token: token, on_full: :raise) do
           complete(chat, message, config: config)
         end
       end
 
-      # Submits a streaming LLM call to {BlockingAdapterPool} and returns
-      # a {BlockingAdapterPool::PendingOperation}.
+      # Submits a streaming LLM call to {OffloadPool} and returns
+      # an {OffloadPool::PendingOperation}.
       #
-      # The block is invoked on the blocking-pool worker thread. Agent code must
+      # The block is invoked on an OffloadPool worker thread. Agent code must
       # pass only a lightweight internal sink that posts a value to EventLoop;
       # Application callbacks must never be passed directly to this method.
       #
@@ -71,13 +71,13 @@ module Phronomy
       # provider client; Phronomy does not attach an additional operation timeout.
       #
       # @yield [chunk] streaming chunk on the worker thread
-      # @return [BlockingAdapterPool::PendingOperation]
+      # @return [OffloadPool::PendingOperation]
       # @api private
       def stream_async(chat, message, config: {}, pool: default_pool, &block)
         raise ArgumentError, "stream_async requires a block" unless block
 
         token = config[:cancellation_token]
-        pool.submit(cancellation_token: token) do
+        pool.submit(cancellation_token: token, on_full: :raise) do
           stream(chat, message, config: config) do |chunk|
             token&.raise_if_cancelled!("invocation cancelled during streaming")
             block.call(chunk)
@@ -88,7 +88,7 @@ module Phronomy
       private
 
       def default_pool
-        Phronomy::Runtime.instance.blocking_io
+        Phronomy::Runtime.instance.offload
       end
     end
   end

data/lib/phronomy/llm_adapter/ruby_llm.rb

@@ -4,10 +4,9 @@ module Phronomy
   module LLMAdapter
     # LLM adapter that delegates to the RubyLLM blocking client.
     #
-    # This is the default adapter used by Phronomy agents.  It wraps
-    # +chat.ask+ (and its streaming variant) so that the blocking HTTP
-    # call runs inside {BlockingAdapterPool} rather than on the EventLoop
-    # thread or the caller's thread directly.
+    # This is the default adapter used by Phronomy agents. It wraps
+    # +chat.ask+ (and its streaming variant) so that the synchronous provider
+    # call runs inside {OffloadPool} rather than on the EventLoop thread.
     #
     # @example Explicitly configuring this adapter
     #   Phronomy.configure do |c|

data/lib/phronomy/llm_adapter.rb

@@ -7,8 +7,8 @@ module Phronomy
   # dependency on the RubyLLM blocking client. All LLM calls in
   # {Agent::Base} are routed through the adapter so that:
   #
-  # - Blocking HTTP can be submitted to {BlockingAdapterPool} for bounded
-  #   concurrency and per-operation timeouts.
+  # - Synchronous provider work can be submitted to {OffloadPool} for bounded
+  #   off-EventLoop execution.
   # - Alternative LLM clients can be swapped in without changing agent code.
   #
   # @example Configuring a custom adapter