phronomy 0.22.0 → 0.24.0

data/lib/phronomy/multi_agent/fan_out_invocation.rb

@@ -1,17 +1,14 @@
 # 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)
+      Child = Data.define(:index, :agent, :input, :config)
 
-      attr_reader :id, :phase, :results
+      attr_reader :phase, :results
 
       def initialize(children:, max_concurrency:, on_error:)
-        @id = SecureRandom.uuid.to_s
         @phase = nil
         @children = children
         @max_concurrency = max_concurrency || children.length
@@ -19,15 +16,13 @@ module Phronomy
         @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
+        @child_errors = Array.new(children.length)
+        @fatal_error = nil
         @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
+      def set_graph_metadata(phase: nil)
         @phase = phase
       end
 
@@ -41,9 +36,6 @@ module Phronomy
           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
@@ -69,27 +61,28 @@ module Phronomy
         end
       end
 
-      def start_available!(runtime)
+      def start_available!(runtime, event_sink:)
         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
+            config: child_config
           )
-          @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.
+          @active[child.index] = {
+            handle: handle,
+            token: child_config[:cancellation_token]
+          }
           [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}
-                )
+              event_sink.post(
+                :child_completed,
+                {
+                  index: captured_index,
+                  result: result,
+                  error: error
+                }
               )
             end
           end
@@ -98,13 +91,7 @@ module Phronomy
       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}
-          )
-        )
+        event_sink.post(:driver_failed, {error: caught})
         self
       end
 
@@ -114,7 +101,11 @@ module Phronomy
 
       def failed?
         return true if @fatal_error
-        @on_error == :raise && @pending.empty? && @active.empty? && @child_errors.any?(&:itself)
+
+        @on_error == :raise &&
+          @pending.empty? &&
+          @active.empty? &&
+          @child_errors.any?(&:itself)
       end
 
       def error

data/lib/phronomy/multi_agent/fan_out_session_builder.rb

@@ -16,14 +16,15 @@ module Phronomy
         cancellation_token: nil,
         runtime: Phronomy::Runtime.instance
       )
-        result = Phronomy::Task.deferred(name: "fan-out:#{invocation.id}")
+        result = Phronomy::Task.deferred(name: "fan-out")
 
         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}")
+        session = build(invocation: invocation, runtime: runtime)
+        source = Phronomy::Task.deferred(name: "fan-out-source:#{session.id}")
         source.on_complete do |context, error|
           if error
             result.fail(error)
@@ -34,27 +35,18 @@ module Phronomy
           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"}
-              )
+            session.event_sink.post(
+              :timeout,
+              {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)
-          )
+          session.event_sink.post(:cancel, nil)
         end
-
         result
       rescue => error
         result ||= Phronomy::Task.deferred(name: "fan-out:registration")
@@ -63,7 +55,8 @@ module Phronomy
       end
 
       def self.build(invocation:, runtime:)
-        phase_machine = build_phase_machine(runtime)
+        event_sink = Phronomy::FSMSession::EventSink.new(event_loop: runtime.event_loop)
+        phase_machine = build_phase_machine(runtime, event_sink)
         external_events = {
           child_completed: [{from: :running, to: :running, guard: nil}],
           driver_failed: [{from: :running, to: :failed, guard: nil}],
@@ -72,8 +65,8 @@ module Phronomy
         }
 
         Phronomy::FSMSession.new(
-          id: invocation.id,
           context: invocation,
+          event_sink: event_sink,
           entry_point: :idle,
           entry_actions: {},
           auto_state_set: AUTO_STATE_SET,
@@ -87,7 +80,7 @@ module Phronomy
       end
       private_class_method :build
 
-      def self.build_phase_machine(runtime)
+      def self.build_phase_machine(runtime, event_sink)
         Class.new do
           attr_accessor :context, :current_event
 
@@ -114,7 +107,7 @@ module Phronomy
             event(:cancel) { transition running: :cancelled }
 
             after_transition to: :running do |machine|
-              machine.context.start_available!(runtime)
+              machine.context.start_available!(runtime, event_sink: event_sink)
             end
           end
         end

data/lib/phronomy/multi_agent/orchestrator.rb

@@ -6,11 +6,33 @@ module Phronomy
     class Orchestrator < Agent::Base
       agent_definition id: "orchestrator", version: 1
 
+      # Own one live cancellation token shared with this invocation's static
+      # children, including when Recovery reconstructs the invocation.
+      # @api private
+      def __invocation_config(config)
+        config.merge(cancellation_token: config[:cancellation_token] || Phronomy::Concurrency::CancellationToken.new)
+      end
+
+      # Resumes retained static child coordination with current class wiring.
+      # @api public
+      def resume(execution_id, config: {})
+        if Phronomy::Runtime.in_event_loop_context?
+          raise Phronomy::EventLoopReentrancyError, "Orchestrator#resume cannot block EventLoop"
+        end
+        execution = persistence.executions.load(execution_id)
+        raise Phronomy::Persistence::ConflictError, "Parent execution owner mismatch" unless execution.agent_id == agent_id
+        input = persistence.contents.fetch_text(execution.metadata.fetch("current_input_ref"))
+        result = Phronomy::Agent::ExactExecution.start(agent: self, execution_id: execution_id, input: input, config: config).wait_result
+        raise Phronomy::Agent::RecoverySupport.error_from_failure(result[:error]) if result[:error]
+        result
+      end
+
       def self.subagent(name, agent_class, on_error: :raise, inherit_knowledge: true)
         # 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
+          def self.__framework_owned_operation? = true
           tool_name "dispatch_to_#{name}"
           description "Dispatch work to the #{name} subagent (#{agent_class.name})"
 
@@ -24,6 +46,20 @@ module Phronomy
             ).wait_result
           end
 
+          # Enter exact child reconciliation even when the parent token is
+          # cancelled: an already admitted child must be settled, not forgotten.
+          define_method(:call_async) do |args, cancellation_token: nil, config: {}|
+            if @_orchestrator_context&.fetch(:parent, nil) && config[:phronomy_tool_invocation_id]
+              validated, schema_error = send(:validate_and_coerce, args)
+              raise Phronomy::ToolError, schema_error if schema_error
+              execute_async(**validated, cancellation_token: cancellation_token, config: config)
+            else
+              super(args, cancellation_token: cancellation_token, config: config)
+            end
+          rescue => error
+            Phronomy::Task.deferred(name: "subagent-dispatch-failed").tap { |task| task.fail(error) }
+          end
+
           define_method(:execute_async) do |input:, cancellation_token: nil, config: {}|
             ctx = @_orchestrator_context || {}
             parent_ic = ctx[:invocation_context]
@@ -38,21 +74,19 @@ module Phronomy
               task_config = task_config.merge(invocation_context: child_ic)
             end
 
+            parent = ctx[:parent]
+            if parent && task_config[:phronomy_tool_invocation_id]
+              return DurableSubagentCoordinator.start(parent: parent,
+                tool_invocation_id: task_config.fetch(:phronomy_tool_invocation_id),
+                parent_execution_id: task_config.fetch(:execution_id), config: task_config)
+            end
             agent = agent_class.new
             if inherit_knowledge
               Array(ctx[:knowledge]).each do |entry|
-                agent.add_knowledge(
-                  entry.fetch(:content),
-                  metadata: entry.fetch(:metadata, {})
-                )
+                agent.add_knowledge(entry.fetch(:content), metadata: entry.fetch(:metadata, {}))
               end
             end
-
-            source = agent.invoke_async(
-              input,
-              thread_id: ctx[:thread_id] || parent_ic&.thread_id,
-              config: task_config
-            )
+            source = agent.invoke_async(input, config: task_config)
             result_task = Phronomy::Task.deferred(
               name: "subagent-tool-#{name}"
             )
@@ -151,7 +185,6 @@ module Phronomy
         agent:,
         inputs:,
         config: {},
-        thread_id: nil,
         max_concurrency: nil,
         on_error: :raise,
         timeout: nil,
@@ -161,7 +194,7 @@ module Phronomy
       )
         dispatch_parallel(
           *inputs.map do |input|
-            {agent: agent, input: input, config: config, thread_id: thread_id}
+            {agent: agent, input: input, config: config}
           end,
           max_concurrency: max_concurrency,
           on_error: on_error,
@@ -176,7 +209,6 @@ module Phronomy
         agent:,
         inputs:,
         config: {},
-        thread_id: nil,
         max_concurrency: nil,
         on_error: :raise,
         timeout: nil,
@@ -186,7 +218,7 @@ module Phronomy
       )
         dispatch_parallel_async(
           *inputs.map do |input|
-            {agent: agent, input: input, config: config, thread_id: thread_id}
+            {agent: agent, input: input, config: config}
           end,
           max_concurrency: max_concurrency,
           on_error: on_error,
@@ -201,7 +233,6 @@ module Phronomy
         agent_class,
         input,
         config: nil,
-        thread_id: nil,
         inherit_knowledge: true
       )
         if Phronomy::Runtime.in_event_loop_context?
@@ -213,11 +244,21 @@ module Phronomy
           inherit_knowledge: inherit_knowledge
         ).invoke_async(
           input,
-          config: config || {},
-          thread_id: thread_id
+          config: config || {}
         ).wait_result
       end
 
+      # @api private
+      def __framework_tool_replayable?(name)
+        self.class.registered_subagents.keys.any? { |key| "dispatch_to_#{key}" == name.to_s }
+      end
+
+      # Reserve child identity/input/knowledge in the parent's existing Agent transaction.
+      # @api private
+      def __prepare_coordination_record(execution, tx:)
+        DurableSubagentCoordinator.prepare(self, execution, tx: tx)
+      end
+
       private
 
       def prepare_tool_class(tool_class, invocation: nil)
@@ -230,14 +271,13 @@ module Phronomy
         end&.last
         inherits_knowledge = registration ? registration.fetch(:inherit_knowledge, true) : true
 
-        captured_context = {}
-        captured_context[:knowledge] = active_knowledge_snapshot if inherits_knowledge
+        captured_context = {parent: self}
+        # Invocation-owned Tools inherit the durable child slot's knowledge,
+        # captured by the existing preparation transaction off EventLoop.
+        captured_context[:knowledge] = active_knowledge_snapshot if inherits_knowledge && !invocation
         if invocation
-          captured_context.merge!(
-            thread_id: invocation.thread_id,
-            config: invocation.config,
-            invocation_context: invocation.config[:invocation_context]
-          )
+          captured_context[:config] = invocation.config
+          captured_context[:invocation_context] = invocation.config[:invocation_context]
         end
         captured_context.freeze
 
@@ -291,6 +331,12 @@ module Phronomy
           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)
+          if task.key?(:thread_id) || task.key?("thread_id")
+            raise ArgumentError,
+              "fan-out task generic thread_id was removed; " \
+              "use purpose-specific domain identifiers or application tracing metadata"
+          end
+          _reject_removed_generic_identity_keys!(task.fetch(:config, {}))
         end
       end
 
@@ -324,8 +370,7 @@ module Phronomy
             index: index,
             agent: child_agent,
             input: task.fetch(:input),
-            config: task_config,
-            thread_id: task[:thread_id] || invocation_context&.thread_id
+            config: task_config
           )
         end
       end