phronomy 0.23.0 → 0.24.0

data/lib/phronomy/agent/recovery_coordinator/resolution.rb

@@ -9,7 +9,7 @@ module Phronomy
         private
 
         def begin_resolve_on_event_loop(request)
-          event_loop = Phronomy::Runtime.instance.event_loop
+          event_loop = @runtime.event_loop
           state = event_loop.agent_execution_state(
             request.execution_id
           )
@@ -36,7 +36,7 @@ module Phronomy
           end
 
           descriptor =
-            RecoverySupport.recovery_descriptor(current)
+            coordination_recovery_descriptor(current)
           unless descriptor &&
               Phronomy::Recovery.subject_equal?(
                 descriptor.fetch(:subject),
@@ -74,10 +74,10 @@ module Phronomy
             execution_id: current.execution_id,
             state: :recovery_required
           )
-          task = Phronomy::Runtime.instance.offload.submit(
+          task = @runtime.offload.submit(
             on_full: :raise
           ) do
-            perform_resolution(operation)
+            prepare_resolution(operation)
           end
           task.on_complete do |result, error|
             ready = ResolveReady.new(
@@ -146,13 +146,7 @@ module Phronomy
                 RecoverySupport::RECOVERY_METADATA_KEY => recovery
               )
             )
-            intended = ResolutionResult.new(
-              execution: updated,
-              root: operation.root,
-              continuation: :failed_terminal,
-              failure: failure,
-              appended_records: [].freeze
-            )
+            intended = ResolutionResult.new(execution: updated)
             save_resolution_result(current, intended)
           when :failed
             recovery = {
@@ -166,13 +160,7 @@ module Phronomy
                   recovery
               )
             )
-            intended = ResolutionResult.new(
-              execution: updated,
-              root: operation.root,
-              continuation: :failed_terminal,
-              failure: operation.failure,
-              appended_records: [].freeze
-            )
+            intended = ResolutionResult.new(execution: updated)
             save_resolution_result(current, intended)
           when :succeeded
             # simplecov:disable
@@ -182,7 +170,7 @@ module Phronomy
               )
             updated = nil
             with_resolution_f1_capture do |tx|
-              main = agent.send(:execution_coordinator)
+              main = agent.send(:execution_coordinator_for, agent.__coordination_config)
               snapshot = {
                 llm_results: [{
                   llm_call_id: llm_call_id,
@@ -217,7 +205,8 @@ module Phronomy
                   llm_call_id,
                   outcome
                 )
-              next_phase = subjects.empty? ?
+              framework_subjects, external_subjects = subjects.partition { |entry| agent.__framework_call?(entry.fetch("tool_name")) }
+              next_phase = external_subjects.empty? ?
                 :recovery_provider_completed : :recovery_tools
               metadata = current.metadata.dup
               metadata.delete(
@@ -226,7 +215,21 @@ module Phronomy
               metadata.delete(
                 RecoverySupport::PENDING_LLM_STARTED_AT_KEY
               )
-              if subjects.empty?
+              metadata.delete("framework_calls_pending")
+              metadata["framework_calls_pending"] = true unless framework_subjects.empty?
+              if subjects.any? && Array(metadata[RecoverySupport::TOOL_BATCH_METADATA_KEY]).empty?
+                metadata[RecoverySupport::TOOL_BATCH_METADATA_KEY] = subjects.map do |entry|
+                  {
+                    "tool_invocation_id" => entry.fetch("tool_invocation_id"),
+                    "llm_call_id" => entry.fetch("llm_call_id"),
+                    "tool_call_id" => entry.fetch("tool_call_id"),
+                    "tool_name" => entry.fetch("tool_name"),
+                    "arguments" => RecoverySupport.canonical_copy(entry.fetch("arguments", {})),
+                    "status" => "authorized"
+                  }.freeze
+                end.freeze
+              end
+              if external_subjects.empty?
                 metadata.delete(
                   RecoverySupport::RECOVERY_METADATA_KEY
                 )
@@ -234,7 +237,7 @@ module Phronomy
                 metadata[
                   RecoverySupport::RECOVERY_METADATA_KEY
                 ] = RecoverySupport.build_recovery_hash(
-                  subjects
+                  external_subjects
                 )
               end
               updated = current.with(
@@ -249,18 +252,7 @@ module Phronomy
                 expected_revision: current.execution_revision,
                 execution: updated
               )
-              ResolutionResult.new(
-                execution: updated,
-                root: operation.root,
-                continuation: (
-                  (updated.phase.to_sym ==
-                    :recovery_provider_completed) ?
-                      :provider_completed :
-                      :resolution_required
-                ),
-                failure: nil,
-                appended_records: [].freeze
-              )
+              ResolutionResult.new(execution: updated)
             end
             # simplecov:enable
           end
@@ -321,13 +313,7 @@ module Phronomy
                   resolved_recovery
               )
             )
-            intended = ResolutionResult.new(
-              execution: updated,
-              root: operation.root,
-              continuation: :failed_terminal,
-              failure: failure,
-              appended_records: [].freeze
-            )
+            intended = ResolutionResult.new(execution: updated)
             save_resolution_result(current, intended)
           when :failed
             recovery_with_failure =
@@ -347,18 +333,12 @@ module Phronomy
                   recovery_with_failure
               )
             )
-            intended = ResolutionResult.new(
-              execution: updated,
-              root: operation.root,
-              continuation: :failed_terminal,
-              failure: operation.failure,
-              appended_records: [].freeze
-            )
+            intended = ResolutionResult.new(execution: updated)
             save_resolution_result(current, intended)
           when :succeeded
             updated = nil
             with_resolution_f1_capture do |tx|
-              main = agent.send(:execution_coordinator)
+              main = agent.send(:execution_coordinator_for, agent.__coordination_config)
               result_ref = main.send(
                 :put_runtime_content,
                 tx,
@@ -408,6 +388,13 @@ module Phronomy
                 RecoverySupport.unresolved_subjects(
                   next_recovery
                 )
+              tool_batch = Array(current.metadata[RecoverySupport::TOOL_BATCH_METADATA_KEY]).map do |entry|
+                if entry.fetch("tool_invocation_id") == subject_entry.fetch("tool_invocation_id")
+                  entry.merge("status" => "completed", "result" => operation.result)
+                else
+                  entry
+                end
+              end
               next_phase = unresolved.empty? ?
                 :recovery_tools_completed : :recovery_tools
               updated = current.with(
@@ -415,8 +402,8 @@ module Phronomy
                 working_records:
                   current.working_records + records,
                 metadata: current.metadata.merge(
-                  RecoverySupport::RECOVERY_METADATA_KEY =>
-                    next_recovery
+                  RecoverySupport::RECOVERY_METADATA_KEY => next_recovery,
+                  RecoverySupport::TOOL_BATCH_METADATA_KEY => tool_batch
                 )
               )
               tx.executions.save(
@@ -424,18 +411,7 @@ module Phronomy
                 expected_revision: current.execution_revision,
                 execution: updated
               )
-              ResolutionResult.new(
-                execution: updated,
-                root: operation.root,
-                continuation: (
-                  (updated.phase.to_sym ==
-                    :recovery_tools_completed) ?
-                      :tools_completed :
-                      :resolution_required
-                ),
-                failure: nil,
-                appended_records: [].freeze
-              )
+              ResolutionResult.new(execution: updated)
             end
           end
         end
@@ -480,154 +456,54 @@ module Phronomy
           end
         end
 
-        def apply_resolve_on_event_loop(ready)
-          request = ready.request
-          event_loop = Phronomy::Runtime.instance.event_loop
-          state = event_loop.agent_execution_state(
-            request.execution_id
-          )
-          unless state && state.agent.equal?(agent)
-            request.completion.fail(
-              Phronomy::ExecutionRehydrationRequiredError.new(
-                "recovered execution disappeared before resolution apply"
-              )
-            )
-            return
-          end
-
-          if ready.error
-            reconcile_resolution_f1_on_event_loop(
-              ready,
-              state
-            )
-            return
-          end
+        # Commit/readback and materialization share one worker operation. A read
+        # failure after a confirmed commit must retain that committed execution;
+        # it must not be mistaken for another uncertain resolution write.
+        def prepare_resolution(operation)
+          result = resolve_with_readback(operation)
+          material = prepare_recovery_material(result.execution)
+          ResolutionPreparation.new(execution: result.execution, material: material, error: nil)
+        rescue => error
+          ResolutionPreparation.new(execution: result&.execution, material: nil, error: error)
+        end
 
-          result = ready.result
-          event_loop.replace_agent_execution(
-            request.execution_id,
-            execution: result.execution
-          )
+        def resolve_with_readback(operation)
+          perform_resolution(operation)
+        rescue => error
+          intended = error.intended_result.execution if error.is_a?(ResolutionOutcomeUnknownError)
+          current = agent.persistence.executions.load(operation.execution.execution_id)
+          return ResolutionResult.new(execution: current) if intended && current.to_h == intended.to_h
 
-          case result.continuation
-          when :resolution_required
-            event_loop.mark_agent_execution_admission(
-              agent.agent_id,
-              execution_id: request.execution_id,
-              state: :recovery_required
-            )
-            descriptor =
-              RecoverySupport.recovery_descriptor(
-                result.execution
-              )
-            deliver_resolution_required(
-              result.execution,
-              descriptor
-            )
-            request.completion.complete(
-              {
-                execution_id: request.execution_id,
-                execution_revision:
-                  result.execution.execution_revision,
-                recovery: :resolution_required
-              }.freeze
-            )
-          when :provider_completed
-            observe_recovery_execution(request.completion, result.execution)
-            continue_provider_completed_after_resolution(
-              event_loop,
-              state,
-              result.execution,
-              request.completion
-            )
-          when :tools_completed
-            observe_recovery_execution(request.completion, result.execution)
-            continue_tools_completed_after_resolution(
-              event_loop,
-              state,
-              result.execution,
-              request.completion
-            )
-          when :failed_terminal
-            observe_recovery_execution(request.completion, result.execution)
-            continue_failed_after_resolution(
-              event_loop,
-              state,
-              result.execution,
-              request.completion,
-              result.failure
-            )
-          else
-            request.completion.fail(
-              Phronomy::Error.new(
-                "unknown Recovery continuation: #{result.continuation.inspect}"
-              )
-            )
+          if current.to_h == operation.execution.to_h
+            raise(error.is_a?(ResolutionOutcomeUnknownError) ? error.original_error : error)
           end
-        rescue => caught
-          request.completion.fail(caught)
+          raise Phronomy::Persistence::ConflictError,
+            "Recovery resolution durable outcome conflicts with both expected pre-state and intended post-state"
         end
 
-        def reconcile_resolution_f1_on_event_loop(ready, state)
+        def apply_resolve_on_event_loop(ready)
           request = ready.request
-          intended_result = ready.result
-          if intended_result.nil? &&
-              ready.error.is_a?(ResolutionOutcomeUnknownError)
-            intended_result = ready.error.intended_result
+          event_loop = @runtime.event_loop
+          state = event_loop.agent_execution_state(request.execution_id)
+          unless state && state.agent.equal?(agent)
+            raise Phronomy::ExecutionRehydrationRequiredError,
+              "recovered execution disappeared before resolution apply"
           end
-          intended = intended_result&.execution
-          current = agent.persistence.executions.load(
-            request.execution_id
-          )
-
-          if intended &&
-              current.execution_revision ==
-                  intended.execution_revision &&
-              current.to_h == intended.to_h
-            Phronomy::Runtime.instance.event_loop.replace_agent_execution(
-              request.execution_id,
-              execution: current
-            )
-            synthetic = ResolveReady.new(
-              coordinator: self,
-              request: request,
-              operation: ready.operation,
-              result: intended_result.class.new(
-                execution: current,
-                root: intended_result.root,
-                continuation: intended_result.continuation,
-                failure: intended_result.failure,
-                appended_records:
-                  intended_result.appended_records
-              ),
-              error: nil
-            )
-            apply_resolve_on_event_loop(synthetic)
-            return
+          unless state.execution.equal?(ready.operation.execution) && state.fsm_session_id.nil?
+            raise Phronomy::Persistence::ConflictError,
+              "Recovery execution changed before resolution apply"
           end
+          raise ready.error if ready.error
 
-          if current.execution_revision ==
-              ready.operation.execution.execution_revision &&
-              current.to_h ==
-                  ready.operation.execution.to_h
-            failure = if ready.error.is_a?(
-              ResolutionOutcomeUnknownError
-            )
-              ready.error.original_error
-            else
-              ready.error
-            end
-            request.completion.fail(failure)
-            return
+          result = ready.result
+          if result.execution
+            event_loop.replace_agent_execution(request.execution_id, execution: result.execution)
           end
+          raise result.error if result.error
 
-          request.completion.fail(
-            Phronomy::Persistence::ConflictError.new(
-              "Recovery resolution durable outcome conflicts with both expected pre-state and intended post-state"
-            )
-          )
-        rescue => reconciliation_error
-          request.completion.fail(reconciliation_error)
+          continue_recovery_on_event_loop(result.execution, request.completion, material: result.material)
+        rescue => caught
+          request.completion.fail(caught)
         end
       end
     end

data/lib/phronomy/agent/recovery_coordinator.rb

@@ -37,18 +37,19 @@ module Phronomy
       ResolutionOperation = Data.define(
         :execution, :root, :subject, :outcome, :result, :failure
       )
-      ResolutionResult = Data.define(
-        :execution, :root, :continuation, :failure, :appended_records
-      )
+      ResolutionResult = Data.define(:execution)
+      ResolutionPreparation = Data.define(:execution, :material, :error)
+      RecoveryMaterial = Data.define(:projection, :messages, :assistant_message, :output, :usage)
       RecoveryPlan = Data.define(
         :execution, :root, :manifest, :base_manifest,
-        :projection, :classification
+        :projection, :classification, :material
       )
 
       attr_reader :agent
 
       def initialize(agent)
         @agent = agent
+        @runtime = Phronomy::Runtime.instance
       end
 
       def recover_on_load!
@@ -67,6 +68,11 @@ module Phronomy
             "active AgentExecution belongs to another Agent: #{execution.agent_id}"
         end
 
+        coordination = execution.metadata["coordination"]
+        if coordination && agent.__coordination_config.empty?
+          return agent
+        end
+
         plan = prepare_plan(execution)
         classification = plan.classification
         if classification.disposition ==
@@ -181,7 +187,7 @@ module Phronomy
       private
 
       def post_control(command)
-        Phronomy::Runtime.instance.event_loop.post(
+        @runtime.event_loop.post(
           Phronomy::Event.new(
             type: :agent_control,
             target_id:

data/lib/phronomy/agent/recovery_support.rb

@@ -305,8 +305,8 @@ module Phronomy
         end
       end
 
-      def build_invocation_for_suspended(agent, execution, projection, main_coordinator, listener)
-        request = Phronomy::Agent::ToolApprovalRequest.from_h(
+      def build_invocation_for_suspended(agent, execution, projection, main_coordinator, listener, assistant_message:)
+        request = execution.approval_request && Phronomy::Agent::ToolApprovalRequest.from_h(
           execution.approval_request
         )
         assistant_record = latest_assistant_record(execution)
@@ -315,19 +315,15 @@ module Phronomy
             "suspended execution #{execution.execution_id} has no durable assistant Tool Call message"
         end
 
-        materializer = Phronomy::Agent::RubyLLMMaterializer.new(
-          agent: agent,
-          persistence: agent.persistence
-        )
-        assistant_message = materializer.materialize_journal_record(
-          assistant_record
-        )
-
         config = {
           execution_id: execution.execution_id,
           phronomy_execution_coordinator: main_coordinator,
           phronomy_runtime_projection: projection
-        }
+        }.merge(agent.__coordination_config)
+        config = agent.__invocation_config(config)
+        if execution.metadata["coordination_cancel_requested"]
+          config = config.merge(cancellation_token: Phronomy::Concurrency::CancellationToken.new.cancel!)
+        end
         invocation = Phronomy::Agent::AgentInvocation.new(
           agent: agent,
           input: projection.ask_message,
@@ -359,7 +355,7 @@ module Phronomy
           assistant_record.llm_call_id&.to_s
         )
 
-        by_id = request.items.to_h do |item|
+        by_id = (request ? request.items : []).to_h do |item|
           [item.tool_invocation_id.to_s, item]
         end
         snapshots = Array(execution.metadata[TOOL_BATCH_METADATA_KEY])
@@ -445,12 +441,16 @@ module Phronomy
         child
       end
 
-      def build_chat_for_recovery(agent, execution, projection, main_coordinator, listener)
+      def build_chat_for_recovery(agent, execution, projection, main_coordinator, listener, messages:)
         config = {
           execution_id: execution.execution_id,
           phronomy_execution_coordinator: main_coordinator,
           phronomy_runtime_projection: projection
-        }
+        }.merge(agent.__coordination_config)
+        config = agent.__invocation_config(config)
+        if execution.metadata["coordination_cancel_requested"]
+          config = config.merge(cancellation_token: Phronomy::Concurrency::CancellationToken.new.cancel!)
+        end
         invocation = Phronomy::Agent::AgentInvocation.new(
           agent: agent,
           input: projection.ask_message,
@@ -473,15 +473,7 @@ module Phronomy
           )
         end
 
-        materializer = Phronomy::Agent::RubyLLMMaterializer.new(
-          agent: agent,
-          persistence: agent.persistence
-        )
-        Array(execution.working_records).each do |record|
-          next unless %i[assistant_message tool_message].include?(record.kind.to_sym)
-
-          chat.messages << materializer.materialize_journal_record(record)
-        end
+        messages.each { |message| chat.messages << message }
 
         invocation.chat = chat
         invocation.user_message_sent = true

data/lib/phronomy/agent/ruby_llm_materializer.rb

@@ -105,14 +105,8 @@ module Phronomy
 
         expected_definitions = fetch_json(manifest.tool_definitions_ref)
         additional = @additional_tools
-        if additional.empty? && defined?(Phronomy::MultiAgent::HandoffCapabilityFactory)
-          ordinary_names = ToolDefinitionSet.build(@agent).definitions
-            .map { |definition| definition.fetch("name") }
-          additional = Array(expected_definitions).filter_map do |definition|
-            name = definition.fetch("name")
-            next if ordinary_names.include?(name)
-            Phronomy::MultiAgent::HandoffCapabilityFactory.lookup(name)&.tool_class
-          end
+        if additional.empty?
+          additional = Array(@agent.__coordination_config[:phronomy_handoff_bindings]).map(&:tool_class)
         end
 
         ToolDefinitionSet.build(@agent, additional_tools: additional)

data/lib/phronomy/agent/tool_invocation.rb

@@ -113,7 +113,7 @@ module Phronomy
         @tool_call_id = tool_call.respond_to?(:id) ? tool_call.id : nil
         raw_arguments = tool_call.respond_to?(:arguments) ? (tool_call.arguments || {}) : {}
         @raw_arguments = immutable_copy(raw_arguments)
-        @config = config
+        @config = config.dup.freeze
         @approval_policy = approval_policy
         @approval_context = immutable_copy(approval_context || {})
         @origin = tool&.respond_to?(:tool_origin) ? tool.tool_origin.to_sym : :local
@@ -560,10 +560,12 @@ module Phronomy
             on_full: :raise
           )
         else
+          tool_config = @tool.class.respond_to?(:__framework_owned_operation?) ?
+            @config.merge(phronomy_tool_invocation_id: @id, execution_id: @execution_id).freeze : @config
           @tool.call_async(
             @arguments,
             cancellation_token: @config[:cancellation_token],
-            config: @config
+            config: tool_config
           )
         end
       end

data/lib/phronomy/engine/runtime/team_ownership_registry.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Phronomy
+  class Runtime
+    # Runtime-local Team identity and construction exclusion; no execution state.
+    # @api private
+    class TeamOwnershipRegistry
+      def initialize
+        @mutex = Mutex.new
+        @condition = ConditionVariable.new
+        @owners = {}
+        @constructing = {}
+        @draining = false
+      end
+
+      def fetch(id, klass:, create:, persistence:)
+        @mutex.synchronize do
+          loop do
+            raise Phronomy::RuntimeShutdownError, "Runtime is draining" if @draining
+            if (owner = @owners[id])
+              raise Phronomy::Persistence::ConflictError, "Team #{id} already exists" if create
+              unless owner.is_a?(klass) && owner.persistence.equal?(persistence)
+                raise Phronomy::ConfigurationError, "Team #{id} owner or Persistence mismatch"
+              end
+              return owner
+            end
+            break unless @constructing[id]
+            @condition.wait(@mutex)
+          end
+          @constructing[id] = true
+        end
+        begin
+          owner = yield
+          @mutex.synchronize { @owners[id] = owner }
+          owner
+        ensure
+          @mutex.synchronize do
+            @constructing.delete(id)
+            @condition.broadcast
+          end
+        end
+      end
+
+      def get(id, klass:)
+        @mutex.synchronize do
+          owner = @owners[id]
+          if owner && !owner.is_a?(klass)
+            raise Phronomy::ConfigurationError, "Team #{id} definition mismatch"
+          end
+          owner
+        end
+      end
+
+      def begin_draining
+        @mutex.synchronize do
+          @draining = true
+          @condition.broadcast
+        end
+      end
+
+      def wait_until_stable(deadline)
+        @mutex.synchronize do
+          until @constructing.empty?
+            remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+            return false if remaining <= 0
+            @condition.wait(@mutex, remaining)
+          end
+          true
+        end
+      end
+
+      def shutdown!
+        @mutex.synchronize { @owners.clear }
+      end
+    end
+  end
+end