phronomy 0.23.0 → 0.24.0

data/lib/phronomy/engine/runtime.rb

@@ -4,6 +4,7 @@ require_relative "runtime/timer_queue"
 require_relative "runtime/shutdown_result"
 require_relative "runtime/timer_service"
 require_relative "runtime/agent_ownership_registry"
+require_relative "runtime/team_ownership_registry"
 
 module Phronomy
   class Runtime
@@ -65,6 +66,7 @@ module Phronomy
       )
       @multi_agent_admissions = Phronomy::MultiAgent::AdmissionRegistry.new
       @agent_ownership_registry = AgentOwnershipRegistry.new(runtime: self)
+      @team_ownership_registry = TeamOwnershipRegistry.new
       @lifecycle_mutex = Mutex.new
       @shutdown_mutex = Mutex.new
       @state = :running
@@ -109,6 +111,16 @@ module Phronomy
       loop_instance&.agent_execution_owner(execution_id)
     end
 
+    # @api private
+    def __team_owner(id, klass:, create:, persistence:, &block)
+      @team_ownership_registry.fetch(id, klass: klass, create: create, persistence: persistence, &block)
+    end
+
+    # @api private
+    def __get_team(id, klass:)
+      @team_ownership_registry.get(id.to_s, klass: klass)
+    end
+
     # @api private
     def __create_agent(agent_id, expected_class:, &block)
       @agent_ownership_registry.create(agent_id, expected_class: expected_class, &block)
@@ -226,9 +238,11 @@ module Phronomy
         end
         loop_instance&.begin_draining
         @agent_ownership_registry.begin_draining
+        @team_ownership_registry.begin_draining
 
         admission_idle = @multi_agent_admissions.wait_until_idle(drain_deadline)
         agent_ownership_stable = @agent_ownership_registry.wait_until_stable(drain_deadline)
+        team_ownership_stable = @team_ownership_registry.wait_until_stable(drain_deadline)
         loop_idle = !loop_instance || loop_instance.wait_until_idle(drain_deadline)
 
         @lifecycle_mutex.synchronize do
@@ -243,7 +257,7 @@ module Phronomy
         end
 
         subsystem_error = shutdown_pools_and_timer
-        cleanup_complete = admission_idle && agent_ownership_stable && loop_idle &&
+        cleanup_complete = admission_idle && agent_ownership_stable && team_ownership_stable && loop_idle &&
           (!loop_instance || !loop_instance.thread_alive?) &&
           event_loop_status != :cancel_timeout &&
           subsystem_error.nil?
@@ -256,6 +270,7 @@ module Phronomy
         end
 
         @agent_ownership_registry.shutdown! if cleanup_complete
+        @team_ownership_registry.shutdown! if cleanup_complete
 
         result = ShutdownResult.new(
           runtime_outcome: runtime_outcome,

data/lib/phronomy/multi_agent/durable_subagent_coordinator.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Phronomy
+  module MultiAgent
+    # Agent-owned transactions reserve child work; Task callbacks only wake observers.
+    # @api private
+    class DurableSubagentCoordinator
+      KEY = "multi_agent_coordination_ref"
+
+      def self.prepare(parent, execution, tx:)
+        ref = execution.metadata[KEY]
+        snapshot = ref ? tx.contents.fetch_json(ref) : {"kind" => "static_subagent", "children" => []}
+        children = snapshot.fetch("children").map(&:dup)
+        children.each do |child|
+          begin
+            exact = tx.executions.load(child.fetch("execution_id"))
+          rescue Phronomy::Persistence::NotFoundError
+            next
+          end
+          raise Phronomy::Persistence::ConflictError, "Child owner mismatch" unless exact.agent_id == child.fetch("agent_id")
+          child.merge!("state" => exact.status.to_s, "result_ref" => exact.result_ref, "error_ref" => exact.error_ref)
+        end
+        Array(execution.metadata[Phronomy::Agent::RecoverySupport::TOOL_BATCH_METADATA_KEY]).each do |tool|
+          registration = parent.class.registered_subagents.find { |name, _| "dispatch_to_#{name}" == tool.fetch("tool_name") }
+          next unless registration
+          next if children.any? { |child| child.fetch("slot") == tool.fetch("tool_invocation_id") }
+          name, settings = registration
+          definition = settings.fetch(:agent_class).agent_definition
+          knowledge = settings.fetch(:inherit_knowledge) ? parent.send(:active_knowledge_snapshot) : []
+          children << {
+            "slot" => tool.fetch("tool_invocation_id"), "name" => name.to_s,
+            "definition" => definition.transform_keys(&:to_s),
+            "agent_id" => SecureRandom.uuid, "execution_id" => SecureRandom.uuid,
+            "input_ref" => tx.contents.put_text(tool.fetch("arguments").fetch("input")),
+            "durable_context_ref" => execution.metadata["durable_context_ref"],
+            "knowledge_ref" => tx.contents.put_json(Phronomy::Agent::RecoverySupport.canonical_copy(knowledge)),
+            "state" => "reserved", "result_ref" => nil, "error_ref" => nil,
+            "on_error" => settings.fetch(:on_error).to_s
+          }
+        end
+        return execution if children.empty?
+        value = tx.contents.put_json(snapshot.merge("children" => children))
+        execution.with(execution_revision: execution.execution_revision, metadata: execution.metadata.merge(KEY => value))
+      end
+
+      def self.start(parent:, tool_invocation_id:, parent_execution_id:, config:)
+        runtime = Phronomy::Runtime.instance
+        completion = Phronomy::Task.deferred(name: "durable-subagent:#{tool_invocation_id}")
+        preparation = runtime.offload.submit(on_full: :raise) do
+          current = parent.persistence.executions.load(parent_execution_id)
+          raise Phronomy::Persistence::ConflictError, "Parent owner mismatch" unless current.agent_id == parent.agent_id
+          snapshot = parent.persistence.contents.fetch_json(current.metadata.fetch(KEY))
+          child = snapshot.fetch("children").find { |entry| entry.fetch("slot") == tool_invocation_id }
+          raise Phronomy::ExecutionRehydrationRequiredError, "Missing reserved child slot" unless child
+          definition = parent.class.registered_subagents.find { |name, _| name.to_s == child.fetch("name") }&.last
+          unless definition && definition.fetch(:agent_class).agent_definition.transform_keys(&:to_s) == child.fetch("definition")
+            raise Phronomy::ConfigurationError, "Registered child definition changed: #{child.fetch("name")}"
+          end
+          klass = definition.fetch(:agent_class)
+          id = child.fetch("agent_id")
+          agent = klass.get(id)
+          unless agent
+            begin
+              parent.persistence.agents.load(id)
+              exists = true
+            rescue Phronomy::Persistence::NotFoundError
+              exists = false
+            end
+            listener = parent.send(:_phronomy_event_listener)
+            agent = if exists
+              klass.load(id, persistence: parent.persistence, on_event: listener)
+            else
+              knowledge = parent.persistence.contents.fetch_json(child.fetch("knowledge_ref"))
+              context = Phronomy::Agent::ContextImporter::ImportedContext.new(records: knowledge.map do |item|
+                Phronomy::Agent::ContextImporter::ImportedRecord.new(kind: :knowledge,
+                  channel: :context, role: :user, content: item.fetch("content"),
+                  content_format: :text, metadata: item.fetch("metadata"))
+              end)
+              klass.create(agent_id: id, persistence: parent.persistence,
+                context: context, on_event: listener)
+            end
+          end
+          unless agent.persistence.equal?(parent.persistence)
+            raise Phronomy::ConfigurationError, "Child Persistence instance mismatch"
+          end
+          durable_context = child["durable_context_ref"] && parent.persistence.contents.fetch_json(child["durable_context_ref"])
+          [child, agent, parent.persistence.contents.fetch_text(child.fetch("input_ref")), durable_context]
+        end
+        preparation.on_complete do |prepared, failure|
+          if failure
+            completion.fail(Phronomy::ExecutionRehydrationRequiredError.new("Child reservation requires recovery: #{failure.message}"))
+            next
+          end
+          child, agent, input, durable_context = prepared
+          child_config = {cancellation_token: config[:cancellation_token] || Phronomy::Concurrency::CancellationToken.new,
+                          invocation_context: config[:invocation_context],
+                          phronomy_coordination: {"kind" => "subagent", "parent_execution_id" => parent_execution_id,
+                                                  "parent_agent_id" => parent.agent_id, "slot" => tool_invocation_id}}.compact
+          child_config = child_config.merge(durable_context: durable_context) if child["durable_context_ref"]
+          source = Phronomy::Agent::ExactExecution.start(agent: agent,
+            execution_id: child.fetch("execution_id"), input: input, config: child_config)
+          source.on_complete do |result, error|
+            if error
+              if error.is_a?(Phronomy::CancellationError)
+                completion.fail(error)
+              else
+                completion.fail(Phronomy::ExecutionRehydrationRequiredError.new(
+                  "Child #{child.fetch("execution_id")} is unfinished: #{error.message}"
+                ))
+              end
+            elsif result[:error]
+              if child.fetch("on_error") == "skip"
+                completion.complete(nil)
+              else
+                completion.fail(Phronomy::Agent::RecoverySupport.error_from_failure(result[:error]))
+              end
+            else
+              completion.complete(result[:output])
+            end
+          end
+        rescue => error
+          completion.fail(Phronomy::ExecutionRehydrationRequiredError.new("Child coordination requires recovery: #{error.message}"))
+        end
+        completion
+      rescue => error
+        completion ||= Phronomy::Task.deferred(name: "durable-subagent")
+        completion.fail(error)
+        completion
+      end
+    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,20 +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,
-              config: task_config
-            )
+            source = agent.invoke_async(input, config: task_config)
             result_task = Phronomy::Task.deferred(
               name: "subagent-tool-#{name}"
             )
@@ -213,6 +248,17 @@ module Phronomy
         ).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)
@@ -225,8 +271,10 @@ 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[:config] = invocation.config
           captured_context[:invocation_context] = invocation.config[:invocation_context]