phronomy 0.17.0 → 0.19.0

data/lib/phronomy/multi_agent/fan_out_invocation.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Phronomy
+  module MultiAgent
+    # Mutable FSM context for one fan-out operation.
+    class FanOutInvocation
+      Child = Data.define(:index, :agent, :input, :config, :thread_id)
+
+      attr_reader :id, :phase, :results
+
+      def initialize(children:, max_concurrency:, on_error:)
+        @id = SecureRandom.uuid.to_s
+        @phase = nil
+        @children = children
+        @max_concurrency = max_concurrency || children.length
+        @on_error = on_error
+        @pending = children.dup
+        @active = {}
+        @results = Array.new(children.length)
+        @child_errors = Array.new(children.length)  # indexed by input order
+        @fatal_error = nil   # driver_failed / timeout / cancel
+        @cancelled = false
+        @timed_out = false
+        @session_id = nil
+      end
+
+      def set_graph_metadata(thread_id: nil, phase: nil)
+        @session_id = thread_id if thread_id
+        @phase = phase
+      end
+
+      def handle_fsm_event(event)
+        case event.type
+        when :child_completed
+          payload = event.payload
+          index = payload.fetch(:index)
+          @active.delete(index)
+          child_error = payload[:error]
+          if child_error
+            if @on_error == :raise
+              @child_errors[index] = child_error
+              # Signal cancellation so other children can stop early, but continue
+              # waiting for all active children to respond so we can return the
+              # first error in INPUT ORDER (not arrival order).
+              cancel_active_children! unless @child_errors.any?(&:itself)
+            end
+          else
+            @results[index] = payload[:result]
+          end
+          true
+        when :driver_failed
+          @fatal_error ||= event.payload.fetch(:error)
+          cancel_active_children!
+          true
+        when :timeout
+          @timed_out = true
+          @fatal_error ||= Phronomy::TimeoutError.new(event.payload.fetch(:message))
+          cancel_active_children!
+          true
+        when :cancel
+          @cancelled = true
+          @fatal_error ||= Phronomy::CancellationError.new("fan-out cancelled")
+          cancel_active_children!
+          true
+        else
+          false
+        end
+      end
+
+      def start_available!(runtime)
+        return self if @fatal_error
+
+        while @active.length < @max_concurrency && (child = @pending.shift)
+          child_config = build_child_config(child.config)
+          handle = child.agent.invoke_async(
+            child.input,
+            config: child_config,
+            thread_id: child.thread_id
+          )
+          @active[child.index] = {handle: handle, token: child_config[:cancellation_token]}
+          # [child.index].each creates a block parameter with a unique binding
+          # per iteration, avoiding the while-loop variable capture problem.
+          [child.index].each do |captured_index|
+            handle.on_complete do |result, error|
+              runtime.event_loop.post_to_session(
+                Phronomy::Event.new(
+                  type: :child_completed,
+                  target_id: @id,
+                  payload: {index: captured_index, result: result, error: error}
+                )
+              )
+            end
+          end
+        end
+        self
+      rescue => caught
+        @fatal_error ||= caught
+        cancel_active_children!
+        runtime.event_loop.post_to_session(
+          Phronomy::Event.new(
+            type: :driver_failed,
+            target_id: @id,
+            payload: {error: caught}
+          )
+        )
+        self
+      end
+
+      def completed?
+        !failed? && @pending.empty? && @active.empty?
+      end
+
+      def failed?
+        return true if @fatal_error
+        @on_error == :raise && @pending.empty? && @active.empty? && @child_errors.any?(&:itself)
+      end
+
+      def error
+        @fatal_error || @child_errors.find(&:itself)
+      end
+
+      def timed_out?
+        @timed_out
+      end
+
+      def cancelled?
+        @cancelled
+      end
+
+      private
+
+      def build_child_config(config)
+        config.dup
+      end
+
+      def cancel_active_children!
+        @pending.clear
+        @active.each_value do |entry|
+          entry[:token]&.cancel!
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/multi_agent/fan_out_session_builder.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require "state_machines"
+
+module Phronomy
+  module MultiAgent
+    # Builds and registers a fan-out coordination FSMSession.
+    class FanOutSessionBuilder
+      AUTO_STATE_SET = {idle: true}.freeze
+      DECLARED_STATES = %i[idle running completed failed timed_out cancelled].freeze
+      WAIT_STATES = [].freeze
+
+      def self.start(
+        invocation:,
+        timeout: nil,
+        cancellation_token: nil,
+        runtime: Phronomy::Runtime.instance
+      )
+        result = Phronomy::Task.deferred(name: "fan-out:#{invocation.id}")
+
+        if cancellation_token&.cancelled?
+          result.fail(Phronomy::CancellationError.new("fan-out cancelled"))
+          return result
+        end
+
+        source = Phronomy::Task.deferred(name: "fan-out-source:#{invocation.id}")
+        source.on_complete do |context, error|
+          if error
+            result.fail(error)
+          elsif context.error
+            result.fail(context.error)
+          else
+            result.complete(context.results)
+          end
+        end
+
+        session = build(invocation: invocation, runtime: runtime)
+        runtime.event_loop.register(session, completion: source)
+
+        if timeout
+          runtime.timer_queue.schedule(seconds: timeout) do
+            runtime.event_loop.post_to_session(
+              Phronomy::Event.new(
+                type: :timeout,
+                target_id: invocation.id,
+                payload: {message: "dispatch_parallel timed out after #{timeout}s"}
+              )
+            )
+          end
+        end
+
+        cancellation_token&.on_cancel do
+          runtime.event_loop.post_to_session(
+            Phronomy::Event.new(type: :cancel, target_id: invocation.id, payload: nil)
+          )
+        end
+
+        result
+      rescue => error
+        result ||= Phronomy::Task.deferred(name: "fan-out:registration")
+        result.fail(error)
+        result
+      end
+
+      def self.build(invocation:, runtime:)
+        phase_machine = build_phase_machine(runtime)
+        external_events = {
+          child_completed: [{from: :running, to: :running, guard: nil}],
+          driver_failed: [{from: :running, to: :failed, guard: nil}],
+          timeout: [{from: :running, to: :timed_out, guard: nil}],
+          cancel: [{from: :running, to: :cancelled, guard: nil}]
+        }
+
+        Phronomy::FSMSession.new(
+          id: invocation.id,
+          context: invocation,
+          entry_point: :idle,
+          entry_actions: {},
+          auto_state_set: AUTO_STATE_SET,
+          declared_states: DECLARED_STATES,
+          wait_state_names: WAIT_STATES,
+          external_events: external_events,
+          phase_machine_class: phase_machine,
+          recursion_limit: 10_000,
+          event_loop: runtime.event_loop
+        )
+      end
+      private_class_method :build
+
+      def self.build_phase_machine(runtime)
+        Class.new do
+          attr_accessor :context, :current_event
+
+          state_machine :phase, initial: :idle do
+            state :idle
+            state :running
+            state :completed
+            state :failed
+            state :timed_out
+            state :cancelled
+
+            event :state_completed do
+              transition idle: :running
+            end
+
+            event :child_completed do
+              transition running: :failed, if: ->(m) { m.context&.failed? }
+              transition running: :completed, if: ->(m) { m.context&.completed? }
+              transition running: :running
+            end
+
+            event(:driver_failed) { transition running: :failed }
+            event(:timeout) { transition running: :timed_out }
+            event(:cancel) { transition running: :cancelled }
+
+            after_transition to: :running do |machine|
+              machine.context.start_available!(runtime)
+            end
+          end
+        end
+      end
+      private_class_method :build_phase_machine
+    end
+  end
+end

data/lib/phronomy/multi_agent/handoff.rb

@@ -42,6 +42,7 @@ module Phronomy
         Class.new(Phronomy::Agent::Context::Capability::Base) do
           tool_name tn
           description desc
+          execution_mode :cooperative
           define_method(:execute) { sentinel_value }
         end
       end

data/lib/phronomy/multi_agent/orchestrator.rb

@@ -6,19 +6,32 @@ module Phronomy
     class Orchestrator < Agent::Base
       agent_definition id: "orchestrator", version: 1
 
-      # @api public
       def self.subagent(name, agent_class, on_error: :raise, inherit_knowledge: true)
-        tool_class = Class.new(Phronomy::Agent::Context::Capability::Base) do
+        # A subagent Tool is logically asynchronous: ToolInvocation starts the
+        # child Agent and resumes when its completion Task settles. It must not
+        # occupy an OffloadPool worker while waiting for the child.
+        tool_class = Class.new(Phronomy::Tools::Agent) do
           tool_name "dispatch_to_#{name}"
           description "Dispatch work to the #{name} subagent (#{agent_class.name})"
-          param :input, type: :string, desc: "The task or question for the subagent"
 
           attr_writer :_orchestrator_context
 
-          define_method(:execute) do |input:|
+          define_method(:execute) do |input:, cancellation_token: nil|
+            execute_async(
+              input: input,
+              cancellation_token: cancellation_token,
+              config: {}
+            ).wait_result
+          end
+
+          define_method(:execute_async) do |input:, cancellation_token: nil, config: {}|
             ctx = @_orchestrator_context || {}
             parent_ic = ctx[:invocation_context]
-            task_config = ctx[:config] || {}
+            task_config = (ctx[:config] || {}).merge(config || {})
+
+            if cancellation_token && !task_config[:cancellation_token]
+              task_config = task_config.merge(cancellation_token: cancellation_token)
+            end
 
             if parent_ic && !task_config[:invocation_context]
               child_ic = parent_ic.merge(parent_task_id: parent_ic.task_id)
@@ -35,16 +48,30 @@ module Phronomy
               end
             end
 
-            result = agent.invoke_async(
+            source = agent.invoke_async(
               input,
               thread_id: ctx[:thread_id] || parent_ic&.thread_id,
               config: task_config
-            ).wait_result
-            result[:output]
-          rescue
-            raise if on_error == :raise
-            nil
+            )
+            result_task = Phronomy::Task.deferred(
+              name: "subagent-tool-#{name}"
+            )
+            source.on_complete do |result, error|
+              if error
+                (on_error == :raise) ? result_task.fail(error) : result_task.complete(nil)
+              else
+                result_task.complete(result[:output])
+              end
+            end
+            result_task
+          rescue => error
+            result_task ||= Phronomy::Task.deferred(
+              name: "subagent-tool-#{name}"
+            )
+            (on_error == :raise) ? result_task.fail(error) : result_task.complete(nil)
+            result_task
           end
+          private :execute_async
         end
 
         @_subagent_tool_classes = (@_subagent_tool_classes || []) + [tool_class]
@@ -61,12 +88,10 @@ module Phronomy
         @_subagent_tool_classes || []
       end
 
-      # @api public
       def self.registered_subagents
         @registered_subagents ||= {}
       end
 
-      # @api public
       def dispatch_parallel(
         *tasks,
         max_concurrency: nil,
@@ -76,25 +101,52 @@ module Phronomy
         invocation_context: nil,
         inherit_knowledge: true
       )
-        unless %i[raise skip].include?(on_error)
-          raise ArgumentError, "unknown on_error: #{on_error.inspect}"
-        end
-        if max_concurrency && !(max_concurrency.is_a?(Integer) && max_concurrency.positive?)
-          raise ArgumentError, "max_concurrency must be a positive Integer"
+        if Phronomy::Runtime.in_event_loop_context?
+          raise Phronomy::EventLoopReentrancyError,
+            "dispatch_parallel cannot block the EventLoop; use dispatch_parallel_async"
         end
-
-        bounded_map(
-          tasks,
+        dispatch_parallel_async(
+          *tasks,
           max_concurrency: max_concurrency,
           on_error: on_error,
           timeout: timeout,
           cancellation_token: cancellation_token,
           invocation_context: invocation_context,
           inherit_knowledge: inherit_knowledge
+        ).wait_result
+      end
+
+      def dispatch_parallel_async(
+        *tasks,
+        max_concurrency: nil,
+        on_error: :raise,
+        timeout: nil,
+        cancellation_token: nil,
+        invocation_context: nil,
+        inherit_knowledge: true
+      )
+        validate_parallel_options!(tasks, max_concurrency, on_error)
+        return Phronomy::Task.deferred(name: "fan-out-empty").tap { |task| task.complete([]) } if tasks.empty?
+
+        children = build_fan_out_children(
+          tasks,
+          cancellation_token: cancellation_token,
+          invocation_context: invocation_context,
+          inherit_knowledge: inherit_knowledge
+        )
+        invocation = FanOutInvocation.new(
+          children: children,
+          max_concurrency: max_concurrency || children.length,
+          on_error: on_error
+        )
+        effective_token = cancellation_token || invocation_context&.cancellation_token
+        FanOutSessionBuilder.start(
+          invocation: invocation,
+          timeout: timeout,
+          cancellation_token: effective_token
         )
       end
 
-      # @api public
       def fan_out(
         agent:,
         inputs:,
@@ -120,11 +172,31 @@ module Phronomy
         )
       end
 
-      # Programmatic single-subagent dispatch. Context propagation is explicit:
-      # pass invocation_context in +config+ when this call must inherit a parent.
-      # Active parent Knowledge is inherited by default; pass
-      # +inherit_knowledge: false+ to create an isolated subagent.
-      # @api public
+      def fan_out_async(
+        agent:,
+        inputs:,
+        config: {},
+        thread_id: nil,
+        max_concurrency: nil,
+        on_error: :raise,
+        timeout: nil,
+        cancellation_token: nil,
+        invocation_context: nil,
+        inherit_knowledge: true
+      )
+        dispatch_parallel_async(
+          *inputs.map do |input|
+            {agent: agent, input: input, config: config, thread_id: thread_id}
+          end,
+          max_concurrency: max_concurrency,
+          on_error: on_error,
+          timeout: timeout,
+          cancellation_token: cancellation_token,
+          invocation_context: invocation_context,
+          inherit_knowledge: inherit_knowledge
+        )
+      end
+
       def subagent(
         agent_class,
         input,
@@ -132,6 +204,10 @@ module Phronomy
         thread_id: nil,
         inherit_knowledge: true
       )
+        if Phronomy::Runtime.in_event_loop_context?
+          raise Phronomy::EventLoopReentrancyError,
+            "subagent cannot block the EventLoop; use the async Agent API"
+        end
         build_subagent(
           agent_class,
           inherit_knowledge: inherit_knowledge
@@ -144,8 +220,6 @@ module Phronomy
 
       private
 
-      # Capture the current invocation directly while materializing Tool classes.
-      # No legacy invoke_once/thread-local bridge is involved.
       def prepare_tool_class(tool_class, invocation: nil)
         prepared = super
         return prepared unless self.class._subagent_tool_classes.include?(tool_class)
@@ -174,6 +248,10 @@ module Phronomy
             self._orchestrator_context = captured_context
             super(args, **kwargs)
           end
+          define_method(:call_async) do |args, **kwargs|
+            self._orchestrator_context = captured_context
+            super(args, **kwargs)
+          end
         end
       end
 
@@ -188,11 +266,7 @@ module Phronomy
         end.freeze
       end
 
-      def build_subagent(
-        agent_class,
-        inherit_knowledge: true,
-        knowledge_snapshot: nil
-      )
+      def build_subagent(agent_class, inherit_knowledge: true, knowledge_snapshot: nil)
         agent = agent_class.new
         return agent unless inherit_knowledge
 
@@ -206,80 +280,54 @@ module Phronomy
         agent
       end
 
-      def bounded_map(
+      def validate_parallel_options!(tasks, max_concurrency, on_error)
+        unless %i[raise skip].include?(on_error)
+          raise ArgumentError, "unknown on_error: #{on_error.inspect}"
+        end
+        if max_concurrency && !(max_concurrency.is_a?(Integer) && max_concurrency.positive?)
+          raise ArgumentError, "max_concurrency must be a positive Integer"
+        end
+        tasks.each do |task|
+          raise ArgumentError, "fan-out task must be a Hash" unless task.is_a?(Hash)
+          raise ArgumentError, "fan-out task requires :agent" unless task[:agent]
+          raise ArgumentError, "fan-out task requires :input" unless task.key?(:input)
+        end
+      end
+
+      def build_fan_out_children(
         tasks,
-        max_concurrency:,
-        on_error:,
-        timeout: nil,
-        cancellation_token: nil,
-        invocation_context: nil,
-        inherit_knowledge: true
+        cancellation_token:,
+        invocation_context:,
+        inherit_knowledge:
       )
-        return [] if tasks.empty?
-
-        inheritance_flags = tasks.map do |task|
-          task.fetch(:inherit_knowledge, inherit_knowledge)
-        end
+        inheritance_flags = tasks.map { |task| task.fetch(:inherit_knowledge, inherit_knowledge) }
         knowledge_snapshot = active_knowledge_snapshot if inheritance_flags.any?
 
-        results = Array.new(tasks.length)
-        errors = Array.new(tasks.length)
-        group = Phronomy::Runtime.instance.task_group(
-          limit: max_concurrency || tasks.length
-        )
-        effective_ct = cancellation_token || invocation_context&.cancellation_token
-
-        spawned = tasks.each_with_index.map do |task, index|
-          group.spawn do
-            task_config = task.fetch(:config, {})
-
-            if effective_ct && !task_config[:cancellation_token]
-              task_config = task_config.merge(cancellation_token: effective_ct)
-            end
-
-            if invocation_context && !task_config[:invocation_context]
-              child_ic = invocation_context.merge(
-                parent_task_id: invocation_context.task_id
-              )
-              task_config = task_config.merge(invocation_context: child_ic)
-            end
-
-            task_inherits_knowledge = inheritance_flags[index]
-            agent = build_subagent(
-              task[:agent],
-              inherit_knowledge: task_inherits_knowledge,
-              knowledge_snapshot: knowledge_snapshot
+        tasks.each_with_index.map do |task, index|
+          task_config = task.fetch(:config, {}).dup
+          if cancellation_token && !task_config[:cancellation_token]
+            task_config[:cancellation_token] = cancellation_token
+          end
+          if invocation_context && !task_config[:invocation_context]
+            task_config[:invocation_context] = invocation_context.merge(
+              parent_task_id: invocation_context.task_id
             )
-
-            results[index] = agent.invoke_async(
-              task[:input],
-              config: task_config,
-              thread_id: task[:thread_id] || invocation_context&.thread_id
-            ).wait_result
-          rescue => error
-            errors[index] = error unless on_error == :skip
           end
-        end
 
-        if timeout
-          deadline = Phronomy::Concurrency::Deadline.in(timeout)
-          spawned.each { |task| task.join([deadline.remaining_seconds, 0].max) }
+          child_agent = build_subagent(
+            task.fetch(:agent),
+            inherit_knowledge: inheritance_flags[index],
+            knowledge_snapshot: knowledge_snapshot
+          )
 
-          alive = spawned.select(&:alive?)
-          unless alive.empty?
-            group.cancel_all!
-            raise Phronomy::TimeoutError,
-              "dispatch_parallel timed out after #{timeout}s " \
-              "(#{alive.length} of #{spawned.length} tasks still running)"
-          end
-        else
-          spawned.each(&:wait_result)
+          FanOutInvocation::Child.new(
+            index: index,
+            agent: child_agent,
+            input: task.fetch(:input),
+            config: task_config,
+            thread_id: task[:thread_id] || invocation_context&.thread_id
+          )
         end
-
-        first_error = errors.compact.first
-        raise first_error if first_error
-
-        results
       end
     end
   end

data/lib/phronomy/multi_agent/team_coordinator.rb

@@ -177,6 +177,7 @@ module Phronomy
         Class.new(Phronomy::Agent::Context::Capability::Base) do
           tool_name "enqueue_task"
           description "Add a task to the worker queue."
+          execution_mode :cooperative
           param :description, type: :string, desc: "What the worker agent should do"
           param :metadata, type: :string, desc: "Optional metadata", required: false
 
@@ -197,6 +198,7 @@ module Phronomy
         Class.new(Phronomy::Agent::Context::Capability::Base) do
           tool_name "finalize"
           description "Signal that task generation is complete. Call this after all tasks have been enqueued."
+          execution_mode :cooperative
           param :summary, type: :string, desc: "Brief summary of what was enqueued", required: false
 
           define_method(:execute) do |summary: ""|