phronomy 0.22.0 → 0.23.0

data/lib/phronomy/agent/tool_invocation_session_builder.rb

@@ -40,18 +40,28 @@ module Phronomy
         ]
       }.freeze
 
-      def self.build(tool_invocation:, runtime: Phronomy::Runtime.instance)
-        build_session(tool_invocation: tool_invocation, runtime: runtime)
+      def self.build(
+        tool_invocation:,
+        parent_event_sink:,
+        runtime: Phronomy::Runtime.instance
+      )
+        build_session(
+          tool_invocation: tool_invocation,
+          parent_event_sink: parent_event_sink,
+          runtime: runtime
+        )
       end
 
       def self.build_for_resume(
         tool_invocation:,
+        parent_event_sink:,
         resume_event:,
         resume_phase:,
         runtime: Phronomy::Runtime.instance
       )
         build_session(
           tool_invocation: tool_invocation,
+          parent_event_sink: parent_event_sink,
           runtime: runtime,
           resume_event: resume_event,
           resume_phase: resume_phase
@@ -60,16 +70,18 @@ module Phronomy
 
       def self.build_session(
         tool_invocation:,
+        parent_event_sink:,
         runtime:,
         resume_event: nil,
         resume_phase: nil
       )
-        actions = build_entry_actions(runtime)
+        event_sink = Phronomy::FSMSession::EventSink.new(event_loop: runtime.event_loop)
+        actions = build_entry_actions(runtime, event_sink, parent_event_sink)
         phase_machine = build_phase_machine(actions)
 
         Phronomy::FSMSession.new(
-          id: tool_invocation.id,
           context: tool_invocation,
+          event_sink: event_sink,
           entry_point: :idle,
           phase_machine_class: phase_machine,
           entry_actions: {},
@@ -85,18 +97,18 @@ module Phronomy
       end
       private_class_method :build_session
 
-      def self.build_entry_actions(runtime)
+      def self.build_entry_actions(runtime, event_sink, parent_event_sink)
         {
           validating: [method(:validating_action)],
-          authorizing: [method(:authorizing_action).curry.call(runtime)],
-          awaiting_approval: [method(:awaiting_approval_action).curry.call(runtime)],
-          authorized: [method(:authorized_action).curry.call(runtime)],
+          authorizing: [method(:authorizing_action).curry.call(runtime, event_sink)],
+          awaiting_approval: [method(:awaiting_approval_action).curry.call(parent_event_sink)],
+          authorized: [method(:authorized_action).curry.call(parent_event_sink)],
           queued: [method(:queued_action)],
-          running: [method(:running_action).curry.call(runtime)],
-          completed: [method(:completed_action).curry.call(runtime)],
-          failed: [method(:failed_action).curry.call(runtime)],
-          rejected: [method(:rejected_action).curry.call(runtime)],
-          cancelled: [method(:cancelled_action).curry.call(runtime)]
+          running: [method(:running_action).curry.call(runtime, event_sink)],
+          completed: [method(:completed_action).curry.call(parent_event_sink)],
+          failed: [method(:failed_action).curry.call(parent_event_sink)],
+          rejected: [method(:rejected_action).curry.call(parent_event_sink)],
+          cancelled: [method(:cancelled_action).curry.call(parent_event_sink)]
         }
       end
       private_class_method :build_entry_actions
@@ -183,24 +195,24 @@ module Phronomy
       end
       private_class_method :validating_action
 
-      def self.authorizing_action(runtime, invocation)
+      def self.authorizing_action(runtime, event_sink, invocation)
         invocation.start_authorization(runtime: runtime) do |outcome|
-          post_to_invocation(runtime, invocation.id, :authorization_completed, outcome)
+          post_to_session(event_sink, :authorization_completed, outcome)
         end
         invocation
       end
       private_class_method :authorizing_action
 
-      def self.awaiting_approval_action(runtime, invocation)
+      def self.awaiting_approval_action(parent_event_sink, invocation)
         invocation.mark_awaiting_approval!
-        notify_parent(runtime, invocation, :tool_approval_required)
+        notify_parent(parent_event_sink, invocation, :tool_approval_required)
         invocation
       end
       private_class_method :awaiting_approval_action
 
-      def self.authorized_action(runtime, invocation)
+      def self.authorized_action(parent_event_sink, invocation)
         invocation.mark_authorized!
-        notify_parent(runtime, invocation, :tool_authorized)
+        notify_parent(parent_event_sink, invocation, :tool_authorized)
         invocation
       end
       private_class_method :authorized_action
@@ -210,61 +222,53 @@ module Phronomy
       end
       private_class_method :queued_action
 
-      def self.running_action(runtime, invocation)
+      def self.running_action(runtime, event_sink, invocation)
         invocation.start_execution(runtime: runtime) do |outcome|
-          post_to_invocation(runtime, invocation.id, :execution_completed, outcome)
+          post_to_session(event_sink, :execution_completed, outcome)
         end
         invocation.mark_running!
         invocation
       end
       private_class_method :running_action
 
-      def self.completed_action(runtime, invocation)
-        notify_parent(runtime, invocation, :tool_completed)
+      def self.completed_action(parent_event_sink, invocation)
+        notify_parent(parent_event_sink, invocation, :tool_completed)
         invocation
       end
       private_class_method :completed_action
 
-      def self.failed_action(runtime, invocation)
-        notify_parent(runtime, invocation, :tool_failed)
+      def self.failed_action(parent_event_sink, invocation)
+        notify_parent(parent_event_sink, invocation, :tool_failed)
         invocation
       end
       private_class_method :failed_action
 
-      def self.rejected_action(runtime, invocation)
+      def self.rejected_action(parent_event_sink, invocation)
         invocation.mark_rejected!
-        notify_parent(runtime, invocation, :tool_rejected)
+        notify_parent(parent_event_sink, invocation, :tool_rejected)
         invocation
       end
       private_class_method :rejected_action
 
-      def self.cancelled_action(runtime, invocation)
+      def self.cancelled_action(parent_event_sink, invocation)
         invocation.mark_cancelled!
-        notify_parent(runtime, invocation, :tool_cancelled)
+        notify_parent(parent_event_sink, invocation, :tool_cancelled)
         invocation
       end
       private_class_method :cancelled_action
 
-      def self.post_to_invocation(runtime, id, event_type, payload)
-        accepted = runtime.event_loop.post_to_session(
-          Phronomy::Event.new(type: event_type, target_id: id, payload: payload)
-        )
-        return if accepted
+      def self.post_to_session(event_sink, event_type, payload)
+        return if event_sink.post(event_type, payload)
 
         Phronomy.configuration.logger&.warn(
-          "[Phronomy] Dropped #{event_type.inspect} for ToolInvocation #{id}"
+          "[Phronomy] Dropped #{event_type.inspect} for " \
+          "FSMSession #{event_sink.fsm_session_id}"
         )
       end
-      private_class_method :post_to_invocation
-
-      def self.notify_parent(runtime, invocation, event_type)
-        runtime.event_loop.post_to_session(
-          Phronomy::Event.new(
-            type: event_type,
-            target_id: invocation.parent_agent_invocation_id,
-            payload: {tool_invocation_id: invocation.id}
-          )
-        )
+      private_class_method :post_to_session
+
+      def self.notify_parent(parent_event_sink, invocation, event_type)
+        parent_event_sink.post(event_type, {tool_invocation_id: invocation.id})
       end
       private_class_method :notify_parent
     end

data/lib/phronomy/agent.rb

@@ -4,12 +4,26 @@ module Phronomy
   module Agent
     StreamEvent = Data.define(:type, :payload)
 
-    def self.run_once(definition:, input:, context: nil, knowledge: [], **invoke_options)
+    def self.run_once(
+      definition:,
+      input:,
+      context: nil,
+      knowledge: [],
+      on_event: nil,
+      **invoke_options,
+      &event_block
+    )
+      if on_event && event_block
+        raise ArgumentError, "Provide either on_event: or a block, not both"
+      end
+
       persistence = Phronomy::Persistence::InMemory.new
       agent = definition.create(
         context: context,
         knowledge: knowledge,
-        persistence: persistence
+        persistence: persistence,
+        on_event: on_event,
+        &event_block
       )
       agent.invoke(input, **invoke_options)
     end
@@ -21,3 +35,7 @@ require_relative "agent/async_event_api"
 unless Phronomy::Agent::Base < Phronomy::Agent::AsyncEventApi
   Phronomy::Agent::Base.prepend(Phronomy::Agent::AsyncEventApi)
 end
+
+# Durable Agent Recovery and Agent-incarnation event binding.
+require_relative "agent/recovery_support"
+require_relative "agent/recovery_coordinator"

data/lib/phronomy/agent_already_exists_error.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Phronomy
+  class AgentAlreadyExistsError < Phronomy::Error; end
+end

data/lib/phronomy/agent_purged_error.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Phronomy
+  class AgentPurgedError < Phronomy::Error; end
+end

data/lib/phronomy/engine/concurrency/offload_pool.rb

@@ -65,7 +65,9 @@ module Phronomy
           @timeout = timeout
           @cancellation_token = cancellation_token
           @on_abandoned = on_abandoned
-          @task = Phronomy::Task.deferred(name: task_name)
+          @task = Phronomy::Concurrency::PhysicalCompletionTask.deferred(
+            name: task_name
+          )
           @settled = false
           @timed_out = false
           @cancelled = false
@@ -162,6 +164,7 @@ module Phronomy
           else
             @task.complete(nil)
           end
+          @task.mark_physical_complete!
           changed
         end
 
@@ -224,6 +227,7 @@ module Phronomy
 
           detach_submit_cancellation
           notify_abandoned if abandoned_now
+          @task.mark_physical_complete! unless abandoned_now
           if cancelled
             @task.cancel!(error)
           else
@@ -251,18 +255,26 @@ module Phronomy
 
         def complete_with_value!(value)
           changed = claim_terminal!
-          return false unless changed
+          unless changed
+            @task.mark_physical_complete!
+            return false
+          end
 
           detach_submit_cancellation
+          @task.mark_physical_complete!
           @task.complete(value)
           true
         end
 
         def complete_with_error!(error)
           changed = claim_terminal!
-          return false unless changed
+          unless changed
+            @task.mark_physical_complete!
+            return false
+          end
 
           detach_submit_cancellation
+          @task.mark_physical_complete!
           @task.fail(error)
           true
         end
@@ -581,6 +593,8 @@ module Phronomy
             @completed_count += 1
           end
 
+          operation.task.mark_physical_complete!
+
           if abandoned
             @logger&.warn do
               "OffloadPool: worker finished after caller-facing timeout/cancellation settlement"

data/lib/phronomy/engine/concurrency/physical_completion_task.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Concurrency
+    # Private Task specialization used when logical completion and physical
+    # completion are intentionally different boundaries.
+    #
+    # Offload cancellation/timeout may settle the caller-facing Task while a
+    # worker is still executing. EventLoop supervision must observe the later
+    # physical-completion boundary without adding domain-specific state to the
+    # public Phronomy::Task contract.
+    #
+    # @api private
+    class PhysicalCompletionTask < Phronomy::Task
+      # @api private
+      def initialize(name: nil, parent: nil)
+        super
+        @physical_mutex = Mutex.new
+        @physical_complete = false
+        @physical_callbacks = []
+      end
+
+      # @return [Boolean]
+      # @api private
+      def physical_complete?
+        @physical_mutex.synchronize { @physical_complete }
+      end
+
+      # Registers a callback that fires only when the underlying physical work
+      # can no longer affect the owning execution.
+      #
+      # @return [self]
+      # @api private
+      def on_physical_complete(&callback)
+        raise ArgumentError, "on_physical_complete requires a block" unless callback
+
+        fire_now = @physical_mutex.synchronize do
+          if @physical_complete
+            true
+          else
+            @physical_callbacks << callback
+            false
+          end
+        end
+        deliver_physical_callback(callback) if fire_now
+        self
+      end
+
+      # Idempotently marks the physical work boundary complete.
+      #
+      # @return [self]
+      # @api private
+      def mark_physical_complete!
+        callbacks = @physical_mutex.synchronize do
+          return self if @physical_complete
+
+          @physical_complete = true
+          current = @physical_callbacks
+          @physical_callbacks = []
+          current
+        end
+        callbacks.each { |callback| deliver_physical_callback(callback) }
+        self
+      end
+
+      # Preserves the physical-completion boundary across Task#map.
+      #
+      # A mapped PhysicalCompletionTask is physically complete only after both:
+      # 1. the source Task's underlying physical work is complete; and
+      # 2. the mapping callback itself has finished running.
+      #
+      # The second condition is required because Task completion callbacks may run
+      # on the OffloadPool worker that settles the source Task. Propagating the
+      # source physical signal immediately could otherwise let EventLoop declare
+      # the owning Execution quiescent while the mapping callback is still active.
+      #
+      # Logical success/failure semantics intentionally remain the same as
+      # Phronomy::Task#map.
+      #
+      # @api public
+      def map(&block)
+        raise ArgumentError, "map requires a block" unless block
+
+        mapped = self.class.deferred(name: "#{name}-mapped", parent: parent)
+        propagation_mutex = Mutex.new
+        source_physical_complete = physical_complete?
+        mapping_complete = false
+
+        mark_mapped_physical_if_ready = lambda do
+          ready = propagation_mutex.synchronize do
+            source_physical_complete && mapping_complete
+          end
+          mapped.mark_physical_complete! if ready
+        end
+
+        on_physical_complete do
+          propagation_mutex.synchronize { source_physical_complete = true }
+          mark_mapped_physical_if_ready.call
+        end
+
+        on_complete do |value, error|
+          if error
+            propagation_mutex.synchronize { mapping_complete = true }
+            mark_mapped_physical_if_ready.call
+            mapped.fail(error)
+            next
+          end
+
+          begin
+            transformed = block.call(value)
+            propagation_mutex.synchronize { mapping_complete = true }
+            mark_mapped_physical_if_ready.call
+            mapped.complete(transformed)
+          rescue => mapped_error
+            propagation_mutex.synchronize { mapping_complete = true }
+            mark_mapped_physical_if_ready.call
+            mapped.fail(mapped_error)
+          end
+        end
+
+        mapped
+      end
+
+      private
+
+      def deliver_physical_callback(callback)
+        callback.call
+      rescue => error
+        Phronomy.configuration.logger&.error do
+          "[PhysicalCompletionTask] callback raised #{error.class}: #{error.message}"
+        end
+      end
+    end
+  end
+end