phronomy 0.25.0 → 0.26.0

data/lib/phronomy/multi_agent/orchestrator.rb

@@ -6,6 +6,9 @@ module Phronomy
     class Orchestrator < Agent::Base
       agent_definition id: "orchestrator", version: 1
 
+      ParallelChild = Data.define(:index, :agent, :input, :config)
+      private_constant :ParallelChild
+
       # Own one live cancellation token shared with this invocation's static
       # children, including when Recovery reconstructs the invocation.
       # @api private
@@ -29,7 +32,7 @@ module Phronomy
 
       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
+        # child Agent and resumes when its completion TaskResult 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
@@ -57,7 +60,7 @@ module Phronomy
               super(args, cancellation_token: cancellation_token, config: config)
             end
           rescue => error
-            Phronomy::Task.deferred(name: "subagent-dispatch-failed").tap { |task| task.fail(error) }
+            Phronomy::TaskResult.deferred(name: "subagent-dispatch-failed").tap { |task| task.fail(error) }
           end
 
           define_method(:execute_async) do |input:, cancellation_token: nil, config: {}|
@@ -87,7 +90,7 @@ module Phronomy
               end
             end
             source = agent.invoke_async(input, config: task_config)
-            result_task = Phronomy::Task.deferred(
+            result_task = Phronomy::TaskResult.deferred(
               name: "subagent-tool-#{name}"
             )
             source.on_complete do |result, error|
@@ -99,7 +102,7 @@ module Phronomy
             end
             result_task
           rescue => error
-            result_task ||= Phronomy::Task.deferred(
+            result_task ||= Phronomy::TaskResult.deferred(
               name: "subagent-tool-#{name}"
             )
             (on_error == :raise) ? result_task.fail(error) : result_task.complete(nil)
@@ -160,73 +163,38 @@ module Phronomy
         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
-
-      def fan_out(
-        agent:,
-        inputs:,
-        config: {},
-        max_concurrency: nil,
-        on_error: :raise,
-        timeout: nil,
-        cancellation_token: nil,
-        invocation_context: nil,
-        inherit_knowledge: true
-      )
-        dispatch_parallel(
-          *inputs.map do |input|
-            {agent: agent, input: input, config: config}
-          end,
-          max_concurrency: max_concurrency,
-          on_error: on_error,
-          timeout: timeout,
-          cancellation_token: cancellation_token,
-          invocation_context: invocation_context,
+          cancellation_token: nil,
+          invocation_context: nil,
           inherit_knowledge: inherit_knowledge
         )
-      end
+        Phronomy::Execution.send(:__run_async, children,
+          timeout: timeout, cancellation_token: cancellation_token,
+          invocation_context: invocation_context, concurrency_limit: max_concurrency) do |child, execution|
+          # Preserve a child-specific context as well as this dispatch's controls.
+          # Agent admission adds that context's constraints to the supplied token.
+          binding = Phronomy::Execution.__operation_binding(
+            invocation_context: execution.invocation_context,
+            cancellation_token: child.config[:cancellation_token]
+          )
+          child_context = child.config[:invocation_context] ||
+            execution.invocation_context.merge(parent_task_id: invocation_context&.task_id)
+          begin
+            source = child.agent.invoke_async(child.input,
+              config: child.config.merge(cancellation_token: binding.token),
+              invocation_context: child_context)
+            binding.track(source)
+          rescue
+            binding.close
+            raise
+          end
+        end.map do |outcomes|
+          failure = outcomes.find { |outcome| outcome.status != :completed }
+          raise failure.error if failure && on_error == :raise
 
-      def fan_out_async(
-        agent:,
-        inputs:,
-        config: {},
-        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}
-          end,
-          max_concurrency: max_concurrency,
-          on_error: on_error,
-          timeout: timeout,
-          cancellation_token: cancellation_token,
-          invocation_context: invocation_context,
-          inherit_knowledge: inherit_knowledge
-        )
+          outcomes.map { |outcome| (outcome.status == :completed) ? outcome.value : nil }
+        end
       end
 
       def subagent(
@@ -366,7 +334,7 @@ module Phronomy
             knowledge_snapshot: knowledge_snapshot
           )
 
-          FanOutInvocation::Child.new(
+          ParallelChild.new(
             index: index,
             agent: child_agent,
             input: task.fetch(:input),

data/lib/phronomy/multi_agent/team_coordinator.rb

@@ -483,14 +483,14 @@ module Phronomy
             param :description, type: :string, desc: "Worker task"
             param :metadata, type: :string, desc: "Optional metadata", required: false
           else
-            param :summary, type: :string, desc: "Task summary", required: false
+            param :summary, type: :string, desc: "TaskResult summary", required: false
           end
           define_method(:call_async) do |args, cancellation_token: nil, config: {}|
             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)
           rescue => error
-            Phronomy::Task.deferred(name: "team-operation-failed").tap { |task| task.fail(error) }
+            Phronomy::TaskResult.deferred(name: "team-operation-failed").tap { |task| task.fail(error) }
           end
           define_method(:execute_async) do |config: {}, cancellation_token: nil, **arguments|
             key = config.fetch(:phronomy_tool_invocation_id)
@@ -542,7 +542,7 @@ module Phronomy
               raise Phronomy::ConfigurationError, "Cannot enqueue after finalize" if metadata["finalized"]
               task = {"id" => Digest::SHA256.hexdigest(entry_id)[0, 32], "description" => values.fetch("description"), "metadata" => values["metadata"]}
               tasks << task
-              output = "Task ##{tasks.length} enqueued: #{task.fetch("description")}"
+              output = "TaskResult ##{tasks.length} enqueued: #{task.fetch("description")}"
             else
               output = "Finalized. #{tasks.size} task(s) enqueued. #{values["summary"]}".strip
               metadata["finalized"] = true

data/lib/phronomy/testing/eval/scorer/llm_judge.rb

@@ -17,8 +17,10 @@ module Phronomy
             Score:
           PROMPT
 
-          def initialize(model:, prompt_template: DEFAULT_PROMPT, raise_on_error: false)
+          def initialize(model:, provider: nil, assume_model_exists: false, prompt_template: DEFAULT_PROMPT, raise_on_error: false)
             @model = model
+            @provider = provider
+            @assume_model_exists = assume_model_exists
             @prompt_template = prompt_template
             @raise_on_error = raise_on_error
           end
@@ -31,8 +33,8 @@ module Phronomy
               actual: actual.to_s
             )
             response = Phronomy::Runtime.instance.offload.submit do
-              RubyLLM.chat(model: @model).ask(prompt)
-            end.blocking_wait
+              RubyLLM.chat(model: @model, provider: @provider, assume_model_exists: @assume_model_exists).ask(prompt)
+            end.wait_result
             response.content.to_s.strip.scan(/-?\d+\.?\d*/).first.to_f.clamp(0.0, 1.0)
           rescue => error
             raise if @raise_on_error

data/lib/phronomy/testing/fake_clock.rb

@@ -13,10 +13,13 @@ module Phronomy
       end
 
       def advance(seconds)
-        @mutex.synchronize do
+        fired = @mutex.synchronize do
           @now += seconds.to_f
-          fire_expired_callbacks!
+          due, @callbacks = @callbacks.partition { |(t, _)| t <= @now }
+          due
         end
+        # Match TimerQueue: callbacks may dispose or register timers themselves.
+        fired.sort_by { |(t, _)| t }.each { |(_, callback)| callback.call }
         self
       end
 
@@ -29,6 +32,14 @@ module Phronomy
         at(@now + seconds.to_f, &block)
       end
 
+      def cancel(callback)
+        @mutex.synchronize do
+          before = @callbacks.length
+          @callbacks.delete_if { |(_, registered)| registered == callback }
+          before != @callbacks.length
+        end
+      end
+
       def pending_callbacks
         @mutex.synchronize { @callbacks.size }
       end
@@ -50,13 +61,6 @@ module Phronomy
           end
         end
       end
-
-      private
-
-      def fire_expired_callbacks!
-        fired, @callbacks = @callbacks.partition { |(t, _)| t <= @now }
-        fired.sort_by { |(t, _)| t }.each { |(_, callback)| callback.call }
-      end
     end
   end
 end

data/lib/phronomy/tools/agent.rb

@@ -106,7 +106,7 @@ module Phronomy
             "#{self.class.name} asynchronous execution must return a completion handle"
         end
 
-        result_task = Phronomy::Task.deferred(name: "agent-tool-#{name}")
+        result_task = Phronomy::TaskResult.deferred(name: "agent-tool-#{name}")
         source.on_complete do |result, error|
           if error
             settle_async_error(result_task, error)
@@ -123,7 +123,7 @@ module Phronomy
       rescue Phronomy::ToolError, Phronomy::CancellationError => error
         failed_task(error)
       rescue => error
-        result_task = Phronomy::Task.deferred(name: "agent-tool-#{name}")
+        result_task = Phronomy::TaskResult.deferred(name: "agent-tool-#{name}")
         settle_async_error(result_task, error)
         result_task
       end
@@ -133,7 +133,7 @@ module Phronomy
       # Subclasses created by .from_agent and Orchestrator override this method.
       # It deliberately remains private so it is not part of the public Tool API.
       def execute_async(input:, cancellation_token: nil, config: {})
-        task = Phronomy::Task.deferred(name: "agent-tool-#{name}-fallback")
+        task = Phronomy::TaskResult.deferred(name: "agent-tool-#{name}-fallback")
         begin
           task.complete(execute(input: input, cancellation_token: cancellation_token))
         rescue => error
@@ -143,7 +143,7 @@ module Phronomy
       end
 
       def schema_error_task(schema_error)
-        task = Phronomy::Task.deferred(name: "agent-tool-#{name}-schema")
+        task = Phronomy::TaskResult.deferred(name: "agent-tool-#{name}-schema")
         if self.class.on_schema_error == :raise
           task.fail(Phronomy::ToolError.new(
             "#{self.class.name} schema error: #{schema_error}"
@@ -155,7 +155,7 @@ module Phronomy
       end
 
       def failed_task(error)
-        Phronomy::Task.deferred(name: "agent-tool-#{name}-failed").tap do |task|
+        Phronomy::TaskResult.deferred(name: "agent-tool-#{name}-failed").tap do |task|
           task.fail(error)
         end
       end

data/lib/phronomy/vector_store/async_backend.rb

@@ -12,7 +12,7 @@ module Phronomy
     # the framework rather than by each backend.
     #
     # A future genuine native-async backend may adapt its completion into a
-    # {Phronomy::Task} without an OffloadPool worker, but native async override is
+    # {Phronomy::TaskResult} without an OffloadPool worker, but native async override is
     # not part of the current backend SPI.
     #
     # @api private
@@ -24,7 +24,7 @@ module Phronomy
       # @param metadata           [Hash]
       # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil]
       # @param timeout            [Numeric, nil]
-      # @return [Phronomy::Task]
+      # @return [Phronomy::TaskResult]
       # @api public
       def add_async(id:, embedding:, metadata: {}, cancellation_token: nil, timeout: nil)
         Phronomy::Runtime.instance.offload.submit(
@@ -42,7 +42,7 @@ module Phronomy
       # @param k                  [Integer]
       # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil]
       # @param timeout            [Numeric, nil]
-      # @return [Phronomy::Task]
+      # @return [Phronomy::TaskResult]
       # @api public
       def search_async(query_embedding:, k: 5, cancellation_token: nil, timeout: nil)
         Phronomy::Runtime.instance.offload.submit(
@@ -59,7 +59,7 @@ module Phronomy
       # @param id                 [String]
       # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil]
       # @param timeout            [Numeric, nil]
-      # @return [Phronomy::Task]
+      # @return [Phronomy::TaskResult]
       # @api public
       def remove_async(id:, cancellation_token: nil, timeout: nil)
         Phronomy::Runtime.instance.offload.submit(
@@ -75,7 +75,7 @@ module Phronomy
       #
       # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil]
       # @param timeout            [Numeric, nil]
-      # @return [Phronomy::Task]
+      # @return [Phronomy::TaskResult]
       # @api public
       def clear_async(cancellation_token: nil, timeout: nil)
         Phronomy::Runtime.instance.offload.submit(

data/lib/phronomy/vector_store/embeddings/base.rb

@@ -7,7 +7,7 @@ module Phronomy
       #
       # Concrete implementations override {#embed}. Phronomy owns the async
       # bridge: {#embed_async} routes the synchronous implementation through the
-      # bounded OffloadPool and returns a {Phronomy::Task}.
+      # bounded OffloadPool and returns a {Phronomy::TaskResult}.
       #
       # @api public
       class Base
@@ -27,7 +27,7 @@ module Phronomy
         # @param text               [String]
         # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil]
         # @param timeout            [Numeric, nil] operation-wide submit timeout
-        # @return [Phronomy::Task]
+        # @return [Phronomy::TaskResult]
         # @api public
         def embed_async(text, cancellation_token = nil, timeout: nil)
           Phronomy::Runtime.instance.offload.submit(

data/lib/phronomy/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Phronomy
-  VERSION = "0.25.0"
+  VERSION = "0.26.0"
 end

data/lib/phronomy/workflow/phase_machine_builder.rb

@@ -139,7 +139,7 @@ module Phronomy
               machine.context,
               machine.current_event
             )
-            if result.is_a?(Phronomy::Task)
+            if result.is_a?(Phronomy::TaskResult)
               raise Phronomy::InvalidAsyncTransitionActionError,
                 transition_task_error_message(metadata)
             end
@@ -151,9 +151,9 @@ module Phronomy
       def build_entry_callback(callable, state_name)
         ->(machine) {
           result = callable.call(machine.context)
-          if result.is_a?(Phronomy::Task)
+          if result.is_a?(Phronomy::TaskResult)
             raise Phronomy::InvalidAsyncEntryActionError,
-              "Entry action for state #{state_name.inspect} returned Phronomy::Task. " \
+              "Entry action for state #{state_name.inspect} returned Phronomy::TaskResult. " \
               "Start the asynchronous operation, register its callback/listener, " \
               "and return the WorkflowContext or nil."
           end
@@ -164,9 +164,9 @@ module Phronomy
       def build_exit_callback(callable, state_name)
         ->(machine) {
           result = callable.call(machine.context)
-          if result.is_a?(Phronomy::Task)
+          if result.is_a?(Phronomy::TaskResult)
             raise Phronomy::InvalidAsyncEntryActionError,
-              "Exit action for state #{state_name.inspect} returned Phronomy::Task. " \
+              "Exit action for state #{state_name.inspect} returned Phronomy::TaskResult. " \
               "Exit actions are synchronous Run-to-Completion callbacks."
           end
         }
@@ -196,7 +196,7 @@ module Phronomy
       def transition_task_error_message(metadata)
         "Transition action " \
           "#{metadata[:from].inspect} --#{metadata[:event].inspect}--> " \
-          "#{metadata[:to].inspect} returned Phronomy::Task. " \
+          "#{metadata[:to].inspect} returned Phronomy::TaskResult. " \
           "Start the asynchronous operation, register its callback/listener, " \
           "and return the WorkflowContext or nil."
       end

data/lib/phronomy/workflow.rb

@@ -93,7 +93,7 @@ module Phronomy
       #
       # Entry actions are synchronous Run-to-Completion callbacks. To start
       # asynchronous work, register its listener/callback inside the action and
-      # return the context or nil. Returning Phronomy::Task is an error.
+      # return the context or nil. Returning Phronomy::TaskResult is an error.
       def state(name, action: nil)
         @declared_states << name
         entry(name, action) if action
@@ -117,7 +117,7 @@ module Phronomy
       # Transition actions are synchronous Run-to-Completion callbacks executed
       # after the source exit callbacks and before the target entry callbacks.
       # They may start asynchronous work and register listeners, but returning
-      # Phronomy::Task is an error; completion must arrive as a later event.
+      # Phronomy::TaskResult is an error; completion must arrive as a later event.
       def transition(from:, to:, guard: nil, on: nil, action: nil)
         destination = (to == :__finish__) ? FINISH : to
         @transitions << {

data/lib/phronomy/workflow_runner.rb

@@ -216,7 +216,7 @@ module Phronomy
     def start_new_execution(input, config, stable_observer: nil)
       reject_legacy_workflow_identity_key!(config)
       runtime = Phronomy::Runtime.instance
-      result_task = Phronomy::Task.deferred(name: "workflow:preparing")
+      result_task = Phronomy::TaskResult.deferred(name: "workflow:preparing")
       explicit_workflow_instance_id = !config[:workflow_instance_id].nil?
       workflow_instance_id = (config[:workflow_instance_id] || SecureRandom.uuid).to_s.freeze
       Phronomy::Tracing::Automatic.observe_task(
@@ -247,7 +247,7 @@ module Phronomy
     def start_resume_execution(state, input:, event_name:, current_phase:)
       runtime = Phronomy::Runtime.instance
       workflow_instance_id = state.workflow_instance_id.to_s.freeze
-      result_task = Phronomy::Task.deferred(name: "workflow-resume:#{workflow_instance_id}")
+      result_task = Phronomy::TaskResult.deferred(name: "workflow-resume:#{workflow_instance_id}")
       Phronomy::Tracing::Automatic.observe_task(
         result_task,
         "workflow.execution",
@@ -582,7 +582,7 @@ module Phronomy
         fsm_session_id: session.id
       )
 
-      source_task = Phronomy::Task.deferred(name: "workflow-source:#{session.id}")
+      source_task = Phronomy::TaskResult.deferred(name: "workflow-source:#{session.id}")
       source_task.on_complete do |result, error|
         finalize_execution(
           execution: execution,
@@ -797,7 +797,7 @@ module Phronomy
     end
 
     def failed_task(name, error)
-      task = Phronomy::Task.deferred(name: name)
+      task = Phronomy::TaskResult.deferred(name: name)
       fail_task(task, error)
       task
     end

data/scripts/api_snapshot.rb

@@ -70,7 +70,9 @@ def snapshot_entry(klass)
       "public_instance_methods" => own_methods
     }
   else
-    instance_methods = (klass.public_instance_methods - BASELINE_INSTANCE_METHODS).sort
+    internal_context_methods = (klass == Phronomy::InvocationContext) ?
+      %i[__bind_execution __execution_scope] : []
+    instance_methods = (klass.public_instance_methods - BASELINE_INSTANCE_METHODS - internal_context_methods).sort
     class_methods = (klass.public_methods(false) - BASELINE_CLASS_METHODS).sort
     {
       "name" => klass.name,

data/sig/phronomy/agent.rbs

@@ -213,18 +213,18 @@ module Phronomy
       # Public operation methods no longer accept per-invocation event listeners
       # or event-listener blocks.
       def invoke: (untyped input, ?config: Hash[untyped, untyped], ?invocation_context: untyped) -> Hash[Symbol, untyped]
-      def invoke_async: (untyped input, ?config: Hash[untyped, untyped], ?invocation_context: untyped) -> Task[Hash[Symbol, untyped]]
+      def invoke_async: (untyped input, ?config: Hash[untyped, untyped], ?invocation_context: untyped) -> TaskResult[Hash[Symbol, untyped]]
       def stream: (untyped input, ?config: Hash[untyped, untyped], ?invocation_context: untyped) -> Hash[Symbol, untyped]
-      def stream_async: (untyped input, ?config: Hash[untyped, untyped], ?invocation_context: untyped) -> Task[Hash[Symbol, untyped]]
+      def stream_async: (untyped input, ?config: Hash[untyped, untyped], ?invocation_context: untyped) -> TaskResult[Hash[Symbol, untyped]]
 
       def approve: (String execution_id, approval_request_id: String, ?approved: bool, ?config: Hash[untyped, untyped]) -> untyped
-      def approve_async: (String execution_id, approval_request_id: String, ?approved: bool, ?config: Hash[untyped, untyped]) -> Task[untyped]
+      def approve_async: (String execution_id, approval_request_id: String, ?approved: bool, ?config: Hash[untyped, untyped]) -> TaskResult[untyped]
 
       # Resolves a factual Recovery ambiguity. result: is meaningful for
       # :succeeded; error: is required for :failed; neither is used by
       # :not_performed.
       def resolve: (String execution_id, expected_execution_revision: Integer, subject: Hash[Symbol, untyped], outcome: Symbol, ?result: untyped, ?error: Exception) -> untyped
-      def resolve_async: (String execution_id, expected_execution_revision: Integer, subject: Hash[Symbol, untyped], outcome: Symbol, ?result: untyped, ?error: Exception) -> Task[untyped]
+      def resolve_async: (String execution_id, expected_execution_revision: Integer, subject: Hash[Symbol, untyped], outcome: Symbol, ?result: untyped, ?error: Exception) -> TaskResult[untyped]
 
       def transcript: () -> Array[untyped]
       def add_knowledge: (untyped content, ?metadata: Hash[untyped, untyped]) -> self

data/sig/phronomy/extensions.rbs

@@ -28,16 +28,16 @@ module Phronomy
       def clear: () -> untyped
       def size: () -> Integer
 
-      def add_async: (id: String, embedding: Array[Float], ?metadata: Hash[untyped, untyped], ?cancellation_token: Concurrency::CancellationToken?, ?timeout: Numeric?) -> Task[untyped]
-      def search_async: (query_embedding: Array[Float], ?k: Integer, ?cancellation_token: Concurrency::CancellationToken?, ?timeout: Numeric?) -> Task[Array[Hash[Symbol, untyped]]]
-      def remove_async: (id: String, ?cancellation_token: Concurrency::CancellationToken?, ?timeout: Numeric?) -> Task[untyped]
-      def clear_async: (?cancellation_token: Concurrency::CancellationToken?, ?timeout: Numeric?) -> Task[untyped]
+      def add_async: (id: String, embedding: Array[Float], ?metadata: Hash[untyped, untyped], ?cancellation_token: Concurrency::CancellationToken?, ?timeout: Numeric?) -> TaskResult[untyped]
+      def search_async: (query_embedding: Array[Float], ?k: Integer, ?cancellation_token: Concurrency::CancellationToken?, ?timeout: Numeric?) -> TaskResult[Array[Hash[Symbol, untyped]]]
+      def remove_async: (id: String, ?cancellation_token: Concurrency::CancellationToken?, ?timeout: Numeric?) -> TaskResult[untyped]
+      def clear_async: (?cancellation_token: Concurrency::CancellationToken?, ?timeout: Numeric?) -> TaskResult[untyped]
     end
 
     module Embeddings
       class Base
         def embed: (String text, ?Concurrency::CancellationToken? cancellation_token) -> Array[Float]
-        def embed_async: (String text, ?Concurrency::CancellationToken? cancellation_token, ?timeout: Numeric?) -> Task[Array[Float]]
+        def embed_async: (String text, ?Concurrency::CancellationToken? cancellation_token, ?timeout: Numeric?) -> TaskResult[Array[Float]]
       end
     end
   end

data/sig/phronomy/multi_agent.rbs

@@ -5,9 +5,7 @@ module Phronomy
       def self.registered_subagents: () -> Hash[Symbol | String, untyped]
       def resume: (String execution_id, ?config: Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
       def dispatch_parallel: (*Hash[Symbol, untyped] tasks, ?max_concurrency: Integer?, ?on_error: Symbol, ?timeout: Numeric?, ?cancellation_token: untyped, ?invocation_context: untyped, ?inherit_knowledge: bool) -> Array[untyped]
-      def dispatch_parallel_async: (*Hash[Symbol, untyped] tasks, ?max_concurrency: Integer?, ?on_error: Symbol, ?timeout: Numeric?, ?cancellation_token: untyped, ?invocation_context: untyped, ?inherit_knowledge: bool) -> ::Phronomy::Task[untyped]
-      def fan_out: (agent: singleton(::Phronomy::Agent::Base), inputs: Array[untyped], ?config: Hash[Symbol, untyped], ?max_concurrency: Integer?, ?on_error: Symbol, ?timeout: Numeric?, ?cancellation_token: untyped, ?invocation_context: untyped, ?inherit_knowledge: bool) -> Array[untyped]
-      def fan_out_async: (agent: singleton(::Phronomy::Agent::Base), inputs: Array[untyped], ?config: Hash[Symbol, untyped], ?max_concurrency: Integer?, ?on_error: Symbol, ?timeout: Numeric?, ?cancellation_token: untyped, ?invocation_context: untyped, ?inherit_knowledge: bool) -> ::Phronomy::Task[untyped]
+      def dispatch_parallel_async: (*Hash[Symbol, untyped] tasks, ?max_concurrency: Integer?, ?on_error: Symbol, ?timeout: Numeric?, ?cancellation_token: untyped, ?invocation_context: untyped, ?inherit_knowledge: bool) -> ::Phronomy::TaskResult[untyped]
     end
 
     class TeamCoordinator

data/sig/phronomy/runtime.rbs

@@ -1,17 +1,44 @@
 module Phronomy
-  class Task[A]
-    def self.completed: [V] (V value, ?name: String?) -> Task[V]
-                      | (?name: String?) -> Task[nil]
-    def self.failed: (Exception error, ?name: String?) -> Task[untyped]
+  class TaskResult[A]
+    class Outcome[V]
+      attr_reader index: Integer
+      attr_reader status: (:completed | :failed | :cancelled | :unfinished)
+      attr_reader value: V?
+      attr_reader error: Exception?
+    end
+
+    def self.completed: [V] (V value, ?name: String?) -> TaskResult[V]
+                      | (?name: String?) -> TaskResult[nil]
+    def self.failed: (Exception error, ?name: String?) -> TaskResult[untyped]
+    def self.all_settled: [V] (Array[TaskResult[V]] results) -> TaskResult[Array[Outcome[V]]]
     attr_reader name: String?
-    attr_reader parent: Task[untyped]?
+    attr_reader parent: TaskResult[untyped]?
 
     def status: () -> (:pending | :completed | :failed | :cancelled)
     def done?: () -> bool
     def alive?: () -> bool
     def wait_result: (?timeout: Numeric?) -> A
     def on_complete: () { (A?, Exception?) -> void } -> self
-    def map: [B] () { (A) -> B } -> Task[B]
+    def map: [B] () { (A) -> B } -> TaskResult[B]
+    def flat_map: [B] () { (A) -> TaskResult[B] } -> TaskResult[B]
+  end
+
+  class Execution
+    attr_reader invocation_context: InvocationContext
+
+    def self.run_async: [I, V] (Array[I] inputs, ?timeout: Numeric?, ?cancellation_token: Concurrency::CancellationToken?, ?invocation_context: InvocationContext?) { (I, Execution) -> TaskResult[V] } -> TaskResult[Array[TaskResult::Outcome[V]]]
+    def self.run: [I, V] (Array[I] inputs, ?timeout: Numeric?, ?cancellation_token: Concurrency::CancellationToken?, ?invocation_context: InvocationContext?) { (I, Execution) -> TaskResult[V] } -> Array[TaskResult::Outcome[V]]
+    def observe: [V] (TaskResult[V] source_result) -> TaskResult[V]
+  end
+
+  class ExecutionTimeoutError < TimeoutError
+    attr_reader outcomes: Array[TaskResult::Outcome[untyped]]
+    def initialize: (?String message, outcomes: Array[TaskResult::Outcome[untyped]]) -> void
+  end
+
+  class ExecutionCancellationError < CancellationError
+    attr_reader outcomes: Array[TaskResult::Outcome[untyped]]
+    def initialize: (?String message, outcomes: Array[TaskResult::Outcome[untyped]]) -> void
   end
 
   module Concurrency
@@ -44,6 +71,6 @@ end
 
 module Phronomy
   module Blocking
-    def self.call_async: [V] (?timeout: Numeric?, ?cancellation_token: Concurrency::CancellationToken?) { () -> V } -> Task[V]
+    def self.call_async: [V] (?timeout: Numeric?, ?cancellation_token: Concurrency::CancellationToken?, ?invocation_context: InvocationContext?) { () -> V } -> TaskResult[V]
   end
 end

data/sig/phronomy/tool.rbs

@@ -21,7 +21,7 @@ module Phronomy
       def name: () -> String
       def params_schema: () -> untyped
       def call: (Hash[untyped, untyped] args, ?cancellation_token: Concurrency::CancellationToken?) -> untyped
-      def call_async: (Hash[untyped, untyped] args, ?cancellation_token: Concurrency::CancellationToken?, ?config: Hash[untyped, untyped]) -> Task[untyped]
+      def call_async: (Hash[untyped, untyped] args, ?cancellation_token: Concurrency::CancellationToken?, ?config: Hash[untyped, untyped]) -> TaskResult[untyped]
       def requires_approval?: () -> untyped
       def tool_origin: () -> Symbol
       def approval_metadata: () -> Hash[untyped, untyped]

data/sig/phronomy/workflow.rbs

@@ -11,7 +11,7 @@ module Phronomy
     def self.define: (Class context_class, ?persistence: Persistence?) { () -> void } -> Workflow
 
     def invoke: (untyped input, ?config: Hash[untyped, untyped], ?invocation_context: untyped) -> untyped
-    def invoke_async: (untyped input, ?config: Hash[untyped, untyped], ?invocation_context: untyped) -> Task[untyped]
+    def invoke_async: (untyped input, ?config: Hash[untyped, untyped], ?invocation_context: untyped) -> TaskResult[untyped]
     def stream: (untyped input, ?config: Hash[untyped, untyped], ?invocation_context: untyped) { (untyped) -> void } -> untyped
     def resume: (state: untyped, ?input: untyped) -> untyped
     def send_event: (state: untyped, event: Symbol, ?input: untyped) -> untyped