phronomy 0.7.0 → 0.8.0

data/lib/phronomy/agent/lifecycle/phase_machine_builder.rb

@@ -0,0 +1,249 @@
+# frozen_string_literal: true
+
+require "state_machines"
+
+module Phronomy
+  module Agent
+    module Lifecycle
+      # Builds the anonymous state-machine Class used by {WorkflowRunner} to track
+      # workflow phase transitions.
+      #
+      # Extracted from {WorkflowRunner#build_phase_machine_class} to reduce the
+      # span of WorkflowRunner's initializer and to give the FSM construction
+      # logic an explicit, testable home.
+      #
+      # Call {#build} to obtain the generated +Class+. The returned class responds
+      # to +#context+ / +#context=+ and +#async_pending+ / +#async_pending=+, and
+      # has a +state_machine :phase+ definition with all registered transitions and
+      # callbacks.
+      #
+      # @api private
+      class PhaseMachineBuilder
+        # @param entry_point      [Symbol]  initial state for the phase machine
+        # @param declared_states  [Array<Symbol>]  all states declared in the workflow
+        # @param wait_state_names [Array<Symbol>]  states that wait for external events
+        # @param external_events  [Hash{Symbol => Array<Hash>}]
+        #   +{ event_name => [{from:, to:, guard:}, ...] }+
+        # @param entry_actions    [Hash{Symbol => Array<#call>}]
+        #   +{ state_name => [callable, ...] }+
+        # @param action_timeouts  [Hash{Symbol => Numeric}]
+        #   +{ state_name => seconds }+
+        # @param auto_transitions [Array<Hash>]
+        #   +[{ from:, to:, guard: }, ...]+ — all auto-fire transitions
+        # @param exit_actions     [Hash{Symbol => Array<#call>}]
+        #   +{ state_name => [callable, ...] }+
+        # @api private
+        def initialize(
+          entry_point:,
+          declared_states:,
+          wait_state_names:,
+          external_events:,
+          entry_actions:,
+          action_timeouts:,
+          auto_transitions:,
+          exit_actions:
+        )
+          @entry_point = entry_point
+          @declared_states = declared_states
+          @wait_state_names = wait_state_names
+          @external_events = external_events
+          @entry_actions = entry_actions
+          @action_timeouts = action_timeouts
+          @auto_transitions = auto_transitions
+          @exit_actions = exit_actions
+        end
+
+        # Constructs and returns the anonymous phase-machine Class.
+        #
+        # @return [Class] an anonymous class with a +state_machine :phase+ definition
+        # @raise [ArgumentError] if state_machines raises during class construction
+        # @api private
+        def build
+          entry = @entry_point
+          all_states = (@declared_states + @wait_state_names + [:__end__]).uniq
+          auto_trans = @auto_transitions
+          ext_events = @external_events
+          entry_acts = @entry_actions
+          exit_acts = @exit_actions
+          act_timeouts = @action_timeouts
+          build_cb = method(:build_entry_callback)
+
+          Class.new do
+            # Holds the current WorkflowContext so guards and callbacks can read it.
+            attr_accessor :context
+
+            # Set to true by an entry action that returned an awaitable Task.
+            # When true, FSMSession skips the automatic advance_or_halt step and
+            # waits for the async worker thread to post a state_completed event back.
+            attr_accessor :async_pending
+
+            state_machine :phase, initial: entry do
+              all_states.each { |s| state s }
+
+              # Auto-fire transitions: all auto transitions unified under :state_completed.
+              # Includes unguarded (unconditional) and guarded (conditional) transitions.
+              # Declaration order is preserved; guards are evaluated before unguarded fallbacks.
+              event :state_completed do
+                auto_trans.each do |t|
+                  if t[:guard]
+                    guard_proc = t[:guard]
+                    transition t[:from] => t[:to], :if => ->(m) { guard_proc.call(m.context) }
+                  else
+                    transition t[:from] => t[:to]
+                  end
+                end
+              end
+
+              # External events: human-in-the-loop triggers from wait states.
+              ext_events.each do |ev_name, transitions|
+                event ev_name do
+                  transitions.each do |t|
+                    if t[:guard]
+                      guard_proc = t[:guard]
+                      transition t[:from] => t[:to], :if => ->(m) { guard_proc.call(m.context) }
+                    else
+                      transition t[:from] => t[:to]
+                    end
+                  end
+                end
+              end
+
+              # Entry callbacks: fire after_transition into each state.
+              #    Each callable is registered as a separate callback; state_machines
+              #    accumulates them and fires in declaration order.
+              #    If the callable returns a WorkflowContext (e.g. via s.merge(...)),
+              #    the returned context replaces the current one on the tracker.
+              entry_acts.each do |state_name, callables|
+                callables.each do |callable|
+                  cb = build_cb.call(callable, state_name, act_timeouts[state_name])
+                  after_transition to: state_name, &cb
+                end
+              end
+
+              # Exit callbacks: fire before_transition out of each state.
+              #    Each callable is registered as a separate callback; state_machines
+              #    accumulates them and fires in declaration order.
+              exit_acts.each do |state_name, callables|
+                callables.each do |callable|
+                  before_transition from: state_name do |machine|
+                    callable.call(machine.context)
+                  end
+                end
+              end
+            end
+          end
+        rescue => e
+          raise ArgumentError, "Failed to build phase machine: #{e.message}"
+        end
+
+        private
+
+        # Returns a proc suitable for use as an +after_transition+ callback.
+        #
+        # The returned proc accepts a single argument (the phase machine instance),
+        # invokes the entry action callable with the current context, then delegates
+        # the result to {#handle_entry_action_result}.  Capturing this in the
+        # builder's scope lets the anonymous +Class.new+ block stay slim.
+        #
+        # @param callable     [#call]  the entry action
+        # @param state_name   [Symbol] name of the target state (for error messages)
+        # @param timeout_secs [Numeric, nil] seconds before ActionTimeoutError
+        # @return [Proc]
+        # @api private
+        def build_entry_callback(callable, state_name, timeout_secs)
+          handle = method(:handle_entry_action_result)
+          ->(machine) {
+            result = callable.call(machine.context)
+            handle.call(machine, result, state_name, timeout_secs)
+          }
+        end
+
+        # Dispatches the return value of an entry action callable.
+        #
+        # - +Phronomy::Task+            → async or blocking task handling
+        # - +Phronomy::WorkflowContext+ → replaces the machine's context directly
+        # - anything else               → ignored
+        #
+        # @param machine       [Object]           phase machine instance
+        # @param result        [Object]           return value of the entry callable
+        # @param state_name    [Symbol]           name of the entered state
+        # @param timeout_secs  [Numeric, nil]     optional timeout in seconds
+        # @api private
+        def handle_entry_action_result(machine, result, state_name, timeout_secs)
+          if result.is_a?(Phronomy::Task)
+            if Phronomy.configuration.event_loop
+              dispatch_task_in_event_loop(machine, result, state_name, timeout_secs)
+            else
+              await_task_blocking(machine, result, state_name, timeout_secs)
+            end
+          elsif result.is_a?(Phronomy::WorkflowContext)
+            machine.context = result
+          end
+        end
+
+        # Handles a +Phronomy::Task+ return value in EventLoop mode.
+        #
+        # Marks the machine as async-pending and spawns a cooperative background
+        # task that awaits the result, then posts the appropriate event back to
+        # the EventLoop.  +FSMSession+ will skip the automatic +advance_or_halt+
+        # step while +async_pending+ is true.
+        #
+        # @param machine       [Object]       phase machine instance
+        # @param result        [Phronomy::Task]
+        # @param state_name    [Symbol]
+        # @param timeout_secs  [Numeric, nil]
+        # @api private
+        def dispatch_task_in_event_loop(machine, result, state_name, timeout_secs)
+          machine.async_pending = true
+          thread_id = machine.context.thread_id
+          Phronomy::Runtime.instance.spawn(name: "wf-await-#{thread_id}") do
+            enforce_timeout!(result, state_name, timeout_secs)
+            task_result = result.await
+            ev = if task_result.is_a?(Phronomy::WorkflowContext)
+              Phronomy::Event.new(type: :action_completed, target_id: thread_id, payload: task_result)
+            else
+              Phronomy::Event.new(type: :state_completed, target_id: thread_id, payload: nil)
+            end
+            Phronomy::EventLoop.instance.post(ev)
+          rescue => e
+            Phronomy::EventLoop.instance.post(
+              Phronomy::Event.new(type: :error, target_id: thread_id, payload: e)
+            )
+          end
+        end
+
+        # Handles a +Phronomy::Task+ return value in non-EventLoop mode.
+        #
+        # Blocks the current execution context until the task completes or the
+        # optional timeout elapses.
+        #
+        # @param machine       [Object]       phase machine instance
+        # @param result        [Phronomy::Task]
+        # @param state_name    [Symbol]
+        # @param timeout_secs  [Numeric, nil]
+        # @api private
+        def await_task_blocking(machine, result, state_name, timeout_secs)
+          enforce_timeout!(result, state_name, timeout_secs)
+          task_result = result.await
+          machine.context = task_result if task_result.is_a?(Phronomy::WorkflowContext)
+        end
+
+        # Raises +ActionTimeoutError+ if the task does not complete within
+        # +timeout_secs+.  No-op when +timeout_secs+ is +nil+.
+        #
+        # @param result       [Phronomy::Task]
+        # @param state_name   [Symbol]
+        # @param timeout_secs [Numeric, nil]
+        # @api private
+        def enforce_timeout!(result, state_name, timeout_secs)
+          return unless timeout_secs
+          return unless result.join(timeout_secs).nil?
+
+          result.cancel!
+          raise Phronomy::ActionTimeoutError,
+            "Action in state #{state_name.inspect} timed out after #{timeout_secs}s"
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/agent/react_agent.rb

@@ -13,6 +13,10 @@ module Phronomy
         caller_meta = {}
         caller_meta[:user_id] = config[:user_id] if config[:user_id]
         caller_meta[:session_id] = config[:session_id] if config[:session_id]
+        if (ic = config[:invocation_context])
+          caller_meta[:task_id] = ic.task_id if ic.task_id
+          caller_meta[:parent_task_id] = ic.parent_task_id if ic.parent_task_id
+        end
 
         trace("agent.invoke", input: input, **caller_meta) do |_span|
           # Run input guardrails before any LLM interaction.
@@ -68,6 +72,10 @@ module Phronomy
         caller_meta = {}
         caller_meta[:user_id] = config[:user_id] if config[:user_id]
         caller_meta[:session_id] = config[:session_id] if config[:session_id]
+        if (ic = config[:invocation_context])
+          caller_meta[:task_id] = ic.task_id if ic.task_id
+          caller_meta[:parent_task_id] = ic.parent_task_id if ic.parent_task_id
+        end
 
         trace("agent.invoke", input: input, **caller_meta) do |_span|
           run_input_guardrails!(input)
@@ -127,14 +135,14 @@ module Phronomy
         # Run before_completion hooks before each LLM call in the ReAct loop.
         run_before_completion_hooks!(chat, config)
 
-        response = if user_asked
-          # Subsequent loop iteration — history already contains the user message;
-          # just ask the LLM to continue (e.g. after a tool result).
-          chat.complete
-        else
-          # First iteration — add the new user question and call the LLM.
-          chat.ask(extract_message(initial_input))
-        end
+        # Route the LLM call through the configured LLMAdapter so that the
+        # blocking HTTP request runs inside BlockingAdapterPool and the
+        # adapter can be swapped without changing agent code.
+        # Passing nil as message signals the adapter to call chat.complete
+        # (no new user turn) for continuation iterations.
+        adapter = Phronomy.configuration.llm_adapter
+        message = user_asked ? nil : extract_message(initial_input)
+        response = adapter.complete_async(chat, message, config: config).await
 
         usage = Phronomy::TokenUsage.from_tokens(response&.tokens)
         tool_calls = chat.messages.last&.tool_calls
@@ -173,13 +181,18 @@ module Phronomy
         # Run before_completion hooks before each LLM call in the streaming loop.
         run_before_completion_hooks!(chat, config)
 
+        # Route the streaming LLM call through the configured LLMAdapter so that
+        # the blocking HTTP request runs inside BlockingAdapterPool.
+        # Passing nil as message signals the adapter to call chat.complete
+        # (no new user turn) for continuation iterations.
+        # Streaming chunks and tool event callbacks are delivered directly via the
+        # block on the pool worker thread; pending.await yields cooperatively until
+        # streaming is complete.
+        adapter = Phronomy.configuration.llm_adapter
+        message = user_asked ? nil : extract_message(initial_input)
         streaming_block = proc { |chunk| block.call(StreamEvent.new(type: :token, payload: {content: chunk.content})) }
-
-        response = if user_asked
-          chat.complete(&streaming_block)
-        else
-          chat.ask(extract_message(initial_input), &streaming_block)
-        end
+        pending = adapter.stream_async(chat, message, config: config, &streaming_block)
+        response = pending.await
 
         usage = Phronomy::TokenUsage.from_tokens(response&.tokens)
         tool_calls = chat.messages.last&.tool_calls

data/lib/phronomy/agent/runner.rb

@@ -74,7 +74,7 @@ module Phronomy
       def build_handoffs(routes)
         routes.each do |source_agent, target_agents|
           Array(target_agents).each do |target_agent|
-            handoff = Handoff.new(target_agent: target_agent)
+            handoff = Phronomy::MultiAgent::Handoff.new(target_agent: target_agent)
             @sentinel_map[handoff.sentinel] = target_agent
             source_agent._add_handoff_tool(handoff.to_tool_class)
           end
@@ -86,7 +86,7 @@ module Phronomy
           next unless msg.role.to_sym == :tool
 
           content = msg.content.to_s
-          next unless content.start_with?(Handoff::SENTINEL_PREFIX)
+          next unless content.start_with?(Phronomy::MultiAgent::Handoff::SENTINEL_PREFIX)
 
           return @sentinel_map[content]
         end

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