phronomy 0.25.0 → 0.26.0

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: phronomy
 version: !ruby/object:Gem::Version
-  version: 0.25.0
+  version: 0.26.0
 platform: ruby
 authors:
 - Raizo T.C.S
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-09-12 00:00:00.000000000 Z
+date: 2026-09-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ruby_llm
@@ -135,6 +135,7 @@ files:
 - docs/archive/design/historical/00_design_philosophy.md
 - docs/archive/design/historical/01_rubyllm_evaluation.md
 - docs/archive/design/historical/06_design_decisions.md
+- docs/async-composition.md
 - docs/changelog/0.14-and-earlier.md
 - docs/decisions/001-rubyllm-as-provider-layer.md
 - docs/decisions/002-workflow-context-immutability.md
@@ -263,8 +264,12 @@ files:
 - lib/phronomy/engine/concurrency/cancellation_token.rb
 - lib/phronomy/engine/concurrency/deadline.rb
 - lib/phronomy/engine/concurrency/offload_pool.rb
+- lib/phronomy/engine/concurrency/operation_binding.rb
 - lib/phronomy/engine/concurrency/physical_completion_task.rb
 - lib/phronomy/engine/concurrency/pool_registry.rb
+- lib/phronomy/engine/concurrency/result_collector.rb
+- lib/phronomy/engine/concurrency/result_composition.rb
+- lib/phronomy/engine/concurrency/subscriptions.rb
 - lib/phronomy/engine/event_loop.rb
 - lib/phronomy/engine/fsm_session.rb
 - lib/phronomy/engine/runtime.rb
@@ -273,9 +278,12 @@ files:
 - lib/phronomy/engine/runtime/team_ownership_registry.rb
 - lib/phronomy/engine/runtime/timer_queue.rb
 - lib/phronomy/engine/runtime/timer_service.rb
-- lib/phronomy/engine/task.rb
+- lib/phronomy/engine/task_result.rb
 - lib/phronomy/event.rb
+- lib/phronomy/execution.rb
+- lib/phronomy/execution_cancellation_error.rb
 - lib/phronomy/execution_rehydration_required_error.rb
+- lib/phronomy/execution_timeout_error.rb
 - lib/phronomy/filter.rb
 - lib/phronomy/filter/base.rb
 - lib/phronomy/filter/prompt_injection_filter.rb
@@ -293,8 +301,6 @@ files:
 - lib/phronomy/metrics.rb
 - lib/phronomy/multi_agent/admission_registry.rb
 - lib/phronomy/multi_agent/durable_subagent_coordinator.rb
-- lib/phronomy/multi_agent/fan_out_invocation.rb
-- lib/phronomy/multi_agent/fan_out_session_builder.rb
 - lib/phronomy/multi_agent/orchestrator.rb
 - lib/phronomy/multi_agent/parallel_tool_chat.rb
 - lib/phronomy/multi_agent/team_coordinator.rb

data/lib/phronomy/multi_agent/fan_out_invocation.rb

@@ -1,137 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module MultiAgent
-    # Mutable FSM context for one fan-out operation.
-    class FanOutInvocation
-      Child = Data.define(:index, :agent, :input, :config)
-
-      attr_reader :phase, :results
-
-      def initialize(children:, max_concurrency:, on_error:)
-        @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)
-        @fatal_error = nil
-        @cancelled = false
-        @timed_out = false
-      end
-
-      def set_graph_metadata(phase: nil)
-        @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
-              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, 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
-          )
-          @active[child.index] = {
-            handle: handle,
-            token: child_config[:cancellation_token]
-          }
-          [child.index].each do |captured_index|
-            handle.on_complete do |result, error|
-              event_sink.post(
-                :child_completed,
-                {
-                  index: captured_index,
-                  result: result,
-                  error: error
-                }
-              )
-            end
-          end
-        end
-        self
-      rescue => caught
-        @fatal_error ||= caught
-        cancel_active_children!
-        event_sink.post(:driver_failed, {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

@@ -1,118 +0,0 @@
-# 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")
-
-        if cancellation_token&.cancelled?
-          result.fail(Phronomy::CancellationError.new("fan-out cancelled"))
-          return result
-        end
-
-        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)
-          elsif context.error
-            result.fail(context.error)
-          else
-            result.complete(context.results)
-          end
-        end
-
-        runtime.event_loop.register(session, completion: source)
-        if timeout
-          runtime.timer_queue.schedule(seconds: timeout) do
-            session.event_sink.post(
-              :timeout,
-              {message: "dispatch_parallel timed out after #{timeout}s"}
-            )
-          end
-        end
-        cancellation_token&.on_cancel do
-          session.event_sink.post(:cancel, nil)
-        end
-        result
-      rescue => error
-        result ||= Phronomy::Task.deferred(name: "fan-out:registration")
-        result.fail(error)
-        result
-      end
-
-      def self.build(invocation:, 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}],
-          timeout: [{from: :running, to: :timed_out, guard: nil}],
-          cancel: [{from: :running, to: :cancelled, guard: nil}]
-        }
-
-        Phronomy::FSMSession.new(
-          context: invocation,
-          event_sink: event_sink,
-          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, event_sink)
-        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, event_sink: event_sink)
-            end
-          end
-        end
-      end
-      private_class_method :build_phase_machine
-    end
-  end
-end