phronomy 0.7.1 → 0.8.0

data/lib/phronomy/agent/invocation_pipeline.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    # Encapsulates the core per-invocation LLM round-trip for {Agent::Base}.
+    #
+    # {Agent::Base#invoke_once} delegates the body of each LLM turn to this
+    # class, keeping the caller to a thin setup + trace frame (span≈2).
+    # The pipeline executes inside the agent's binding via +instance_exec+
+    # so that private concern methods (guardrails, hooks, cancellation) remain
+    # encapsulated in their original modules while the orchestration logic lives
+    # here.
+    #
+    # @api private
+    class InvocationPipeline
+      # @param agent [Agent::Base] the agent instance driving this invocation
+      # @api private
+      def initialize(agent)
+        @agent = agent
+      end
+
+      # Runs one LLM round-trip inside the agent's execution context.
+      #
+      # Calls private {Agent::Base} concern methods (guardrails, hooks,
+      # cancellation) via +instance_exec+ so that their encapsulation is
+      # preserved, then routes the LLM request through the configured adapter.
+      #
+      # @param input      [String, Hash] the user input for this turn
+      # @param messages   [Array]        prior conversation messages
+      # @param thread_id  [String, nil]  persistence thread identifier
+      # @param config     [Hash]         per-invocation options
+      # @return [Array(Hash, Phronomy::TokenUsage, nil)]
+      #   A two-element array: the result hash and the token usage (or nil on
+      #   suspension).
+      # @api private
+      def run(input, messages:, thread_id:, config:)
+        @agent.instance_exec(input, messages, thread_id, config) do |inp, msgs, tid, cfg|
+          # Run input guardrails before touching the LLM.
+          run_input_guardrails!(inp)
+
+          user_message = extract_message(inp)
+          chat = build_chat
+
+          # Assemble context (system prompt + history). Override #build_context to
+          # inject custom context editing logic at the Agent subclass level.
+          context = build_context(inp, messages: msgs, thread_id: tid, config: cfg)
+          apply_instructions(chat, context[:system]) if context[:system]
+          context[:messages].each { |msg| chat.messages << msg }
+
+          # Run before_completion hooks (global → class → instance) before the LLM call.
+          run_before_completion_hooks!(chat, cfg)
+
+          # Register suspension hook for approval-required tools (no-op when a
+          # synchronous on_approval_required handler is already registered).
+          _register_suspension_hook!(chat)
+
+          # Check for cancellation immediately before the LLM call.
+          check_cancellation!(cfg, "invocation cancelled before LLM call")
+
+          # Forward the cancellation token to ParallelToolChat explicitly
+          # via the chat instance so that tool dispatch batches can observe
+          # cancellation without needing Thread.current.
+          chat.cancellation_token = cfg[:cancellation_token] if chat.respond_to?(:cancellation_token=)
+
+          begin
+            # 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.
+            adapter = Phronomy.configuration.llm_adapter
+            response = adapter.complete_async(chat, user_message, config: cfg).await
+          rescue SuspendSignal => signal
+            checkpoint = Checkpoint.new(
+              thread_id: tid,
+              original_input: inp,
+              messages: chat.messages.dup,
+              pending_tool_name: signal.tool_name,
+              pending_tool_args: signal.args,
+              pending_tool_call_id: signal.tool_call_id
+            )
+            suspended_result = {output: nil, suspended: true, checkpoint: checkpoint, messages: chat.messages}
+            next [suspended_result, nil]
+          ensure
+            # Clear the chat's cancellation token reference after each LLM call.
+            chat.cancellation_token = nil if chat.respond_to?(:cancellation_token=)
+          end
+
+          output = response.content
+          usage = Phronomy::TokenUsage.from_tokens(response.tokens)
+
+          # Run output guardrails before returning to the caller.
+          run_output_guardrails!(output)
+
+          result = {output: output, messages: chat.messages, usage: usage}
+          [result, usage]
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,251 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    module Lifecycle
+      # Event-driven execution wrapper for a single workflow run.
+      #
+      # Created by WorkflowRunner and registered with EventLoop. All public methods
+      # are called from the EventLoop thread — FSMSession is NOT thread-safe and must
+      # not be accessed concurrently from multiple threads.
+      #
+      # == Lifecycle
+      #
+      #   register(session) → EventLoop posts :start → session.start
+      #                                 ↓ (auto-transition present)
+      #                        EventLoop posts :state_completed → session.handle
+      #                                 ↓ (repeat)
+      #                        session posts :finished or :halted
+      #                                 ↓
+      #                        EventLoop pushes ctx to completion_queue → caller unblocks
+      #
+      # == Async IO pattern (EventLoop mode only)
+      #
+      # When a state has no auto-transition and is not a wait_state, but has an
+      # external event registered (e.g. +transition from: :fetching, on: :fetch_done+),
+      # the FSMSession stays registered in the EventLoop and waits for that event.
+      # The entry action is expected to spawn an IO thread that posts the event back:
+      #
+      #   entry :fetching, ->(ctx) {
+      #     Thread.new {
+      #       ctx.result = http.get(ctx.url)
+      #       Phronomy::EventLoop.instance.post(
+      #         Phronomy::Event.new(type: :fetch_done, target_id: ctx.thread_id, payload: nil)
+      #       )
+      #     }
+      #   }
+      #   transition from: :fetching, on: :fetch_done, to: :process
+      class FSMSession
+        FINISH = WorkflowRunner::FINISH
+
+        # @return [String] workflow thread_id (matches WorkflowContext#thread_id)
+        attr_reader :id
+
+        # @param id                  [String]
+        # @param context             [Object]        includes Phronomy::WorkflowContext
+        # @param entry_point         [Symbol]        initial state name
+        # @param entry_actions       [Hash]          { state_name => [callable, ...] }
+        # @param auto_state_set      [Hash]          { state_name => true }
+        # @param declared_states     [Array<Symbol>] all action state names
+        # @param wait_state_names    [Array<Symbol>]
+        # @param external_events     [Hash]          { event_name => [{from:, to:, guard:}] }
+        # @param phase_machine_class [Class]         state_machines-backed phase tracker class
+        # @param recursion_limit     [Integer]
+        # @param action_timeouts     [Hash]          { state_name => seconds }
+        # @param resume_event        [Symbol, nil]   external event to fire when resuming
+        # @param resume_phase        [Symbol, nil]   wait state name to resume from
+        # @api private
+        def initialize(id:, context:, entry_point:, entry_actions:, auto_state_set:,
+          declared_states:, wait_state_names:, external_events:, phase_machine_class:,
+          recursion_limit:, action_timeouts: {}, resume_event: nil, resume_phase: nil)
+          @id = id
+          @ctx = context
+          @entry_point = entry_point
+          @entry_actions = entry_actions
+          @auto_state_set = auto_state_set
+          @declared_states = declared_states
+          @wait_state_names = wait_state_names
+          @external_events = external_events
+          @phase_machine_class = phase_machine_class
+          @recursion_limit = recursion_limit
+          @action_timeouts = action_timeouts
+          @resume_event = resume_event
+          @resume_phase = resume_phase
+          @step = 0
+          @done = false
+          @current_state = nil
+          @tracker = nil
+        end
+
+        # Begins workflow execution. Called by EventLoop on :start event.
+        def start
+          if @resume_event
+            # Resume from wait state: position tracker at the wait state, then fire the
+            # external event. state_machines fires before_transition (exit) and
+            # after_transition (entry) callbacks, so both actions execute here.
+            @current_state = @resume_phase
+            @tracker = build_tracker(@current_state)
+            @tracker.context = @ctx
+            fire_and_advance!(@resume_event)
+          else
+            # Fresh start: state_machines does not fire callbacks on initialization,
+            # so we invoke the entry action for the initial state manually.
+            @current_state = @entry_point
+            @tracker = build_tracker(@current_state)
+            @tracker.context = @ctx
+            (@entry_actions[@current_state] || []).each do |c|
+              result = c.call(@ctx)
+              if result.is_a?(Phronomy::Task)
+                # Awaitable action: spawn a task to await without blocking EventLoop.
+                @tracker.async_pending = true
+                session_id = @id
+                current_state_name = @current_state
+                timeout_secs = @action_timeouts[current_state_name]
+                Phronomy::Runtime.instance.spawn(name: "fsm-await-#{session_id}") do
+                  if timeout_secs
+                    if result.join(timeout_secs).nil?
+                      result.cancel!
+                      raise Phronomy::ActionTimeoutError,
+                        "Action in state #{current_state_name.inspect} timed out after #{timeout_secs}s"
+                    end
+                  end
+                  task_result = result.await
+                  if task_result.is_a?(Phronomy::WorkflowContext)
+                    event_loop.post(Event.new(type: :action_completed, target_id: session_id, payload: task_result))
+                  else
+                    event_loop.post(Event.new(type: :state_completed, target_id: session_id, payload: nil))
+                  end
+                rescue => e
+                  event_loop.post(Event.new(type: :error, target_id: session_id, payload: e))
+                end
+                break # Only one async action at a time per state
+              elsif result.is_a?(Phronomy::WorkflowContext)
+                @ctx = result
+              end
+            end
+            @tracker.context = @ctx
+            advance_or_halt unless @tracker.async_pending
+          end
+        rescue => e
+          finish_with_error(e)
+        end
+
+        # Processes an event dispatched from EventLoop.
+        # Called for :state_completed, :action_completed, and all user-defined external events.
+        #
+        # @param event [Phronomy::Event]
+        # @api private
+        def handle(event)
+          return if @done
+
+          if event.type == :action_completed
+            # An awaitable entry action completed: update context and advance.
+            @ctx = event.payload if event.payload.is_a?(Phronomy::WorkflowContext)
+            @tracker.context = @ctx
+            @tracker.async_pending = false  # Reset flag set by start or fire_and_advance!
+            advance_or_halt
+            return
+          end
+
+          fire_and_advance!(event.type)
+        rescue => e
+          finish_with_error(e)
+        end
+
+        private
+
+        # Fires event_name on the phase tracker, updates @current_state, then
+        # calls advance_or_halt to decide what to do next.
+        def fire_and_advance!(event_name)
+          if @step >= @recursion_limit
+            raise Phronomy::RecursionLimitError,
+              "Recursion limit (#{@recursion_limit}) exceeded"
+          end
+
+          fire_event!(@tracker, event_name, @current_state)
+          @ctx = @tracker.context
+          next_phase = @tracker.phase.to_sym
+          # When next_phase == @current_state, no transition matched → treat as terminal.
+          @current_state = (next_phase == @current_state) ? FINISH : next_phase
+          @step += 1
+
+          # If an entry action returned a Task, the after_transition callback set
+          # async_pending = true and spawned a thread. Skip advance_or_halt — the
+          # background thread will post :action_completed or :state_completed.
+          if @tracker.async_pending
+            @tracker.async_pending = false
+            return
+          end
+
+          advance_or_halt
+        end
+
+        # Determines the next action after the FSM has entered @current_state.
+        def advance_or_halt
+          return finish! if @current_state == FINISH
+
+          if @wait_state_names.include?(@current_state)
+            return halt!
+          end
+
+          if @auto_state_set.key?(@current_state)
+            event_loop.post(Event.new(type: :state_completed, target_id: @id, payload: nil))
+            return
+          end
+
+          if has_external_event_from?(@current_state)
+            # Async IO pattern: the entry action spawned an IO thread that will post
+            # an external event back. Stay registered; do nothing here.
+            return
+          end
+
+          # No transition declared — validate the state is known, then treat as terminal.
+          unless @declared_states.include?(@current_state)
+            raise ArgumentError, "State #{@current_state.inspect} is not defined"
+          end
+
+          finish!
+        end
+
+        def finish!
+          @done = true
+          @ctx.set_graph_metadata(thread_id: @id, phase: :__end__)
+          event_loop.post(Event.new(type: :finished, target_id: @id, payload: @ctx))
+        end
+
+        def halt!
+          @done = true
+          @ctx.set_graph_metadata(thread_id: @id, phase: @current_state)
+          event_loop.post(Event.new(type: :halted, target_id: @id, payload: @ctx))
+        end
+
+        def finish_with_error(err)
+          @done = true
+          event_loop.post(Event.new(type: :error, target_id: @id, payload: err))
+        end
+
+        def fire_event!(tracker, event_name, from_state)
+          return if tracker.send(event_name)
+
+          raise ArgumentError,
+            "Transition from #{from_state.inspect} via event #{event_name.inspect} failed. " \
+            "Ensure at least one guard matches or add a fallback (no-guard) transition."
+        end
+
+        def has_external_event_from?(state)
+          @external_events.any? { |_, transitions| transitions.any? { |t| t[:from] == state } }
+        end
+
+        def build_tracker(from_state)
+          machine = @phase_machine_class.new
+          machine.instance_variable_set(:@phase, from_state.to_s)
+          machine
+        end
+
+        def event_loop
+          Phronomy::EventLoop.instance
+        end
+      end
+    end
+  end
+end

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

@@ -135,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
@@ -181,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