phronomy 0.27.0 → 0.29.0

data/lib/phronomy/agent/admission.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Phronomy
+  module Agent
+    # The short durable phase of an Agent's already acquired runtime admission.
+    # A coordinator may join it to its reservation check; it cannot start an FSM,
+    # publish a provisional result or make the Agent interpret a parent's schema.
+    # @api public
+    class Admission
+      attr_reader :agent_id, :execution_id, :correlation
+
+      # Constructed by Agent execution, never restored from a durable record.
+      # @api private
+      def initialize(persistence:, root:, input:, config:, preparation_metadata:)
+        @persistence, @root, @input, @config = persistence, root, input, config
+        @preparation_metadata = preparation_metadata
+        @agent_id = root.agent_id
+        @execution_id = (config[:phronomy_reserved_execution_id] || SecureRandom.uuid).to_s.freeze
+        @correlation = Phronomy::Values::Immutable.copy(config[:phronomy_reservation])
+        @thread = Thread.current
+      end
+
+      # Own a standalone admission transaction.
+      # @api public
+      def accept
+        @persistence.coordinator.atomic { |scope| accept_in(scope) }
+        nil
+      end
+
+      # Participate without committing or publishing live state.
+      # @api public
+      def accept_in(scope)
+        check_thread!
+        raise Phronomy::ConfigurationError, "Agent admission is single-use" if @scope
+        @scope = scope
+        @persistence.participate(scope) do |records|
+          raise Phronomy::Error, "agent is closed: #{agent_id}" if @root.lifecycle_status == :closed
+          input_ref = records.contents.put_text(@input)
+          context_ref = records.contents.put_json(@config.fetch(:durable_context)) if @config.key?(:durable_context)
+          input_record = JournalRecord.new(agent_id: agent_id, kind: :input_received,
+            channel: :external, role: :user, content_ref: input_ref,
+            context_generation: @root.transcript_generation, context_candidate: false)
+          execution = AgentExecution.start(agent_root: @root, input_record: input_record,
+            execution_id: execution_id, metadata: {
+              "reservation" => correlation, "current_input_ref" => input_ref,
+              "durable_context_ref" => context_ref,
+              "execution_extension" => @config[:phronomy_execution_participant]&.binding&.to_h
+            }.merge(@preparation_metadata).compact)
+          input_record = JournalRecord.from_h(input_record.to_h.merge("execution_id" => execution_id))
+          execution = execution.with(execution_revision: 0, working_records: [input_record])
+          records.executions.create_active(execution)
+          next_root = @root.with(agent_revision: @root.agent_revision + 1, lifecycle_status: :active)
+          records.agents.save(agent_id, expected_revision: @root.agent_revision, root: next_root)
+          @result = [execution, next_root].freeze
+        end
+        nil
+      end
+
+      # Available to Agent execution only after the outermost successful response.
+      # @api private
+      def result
+        check_thread!
+        unless @result && @scope&.committed?
+          raise Phronomy::Persistence::TransactionError, "Agent admission has not committed"
+        end
+        @result
+      end
+
+      private
+
+      def check_thread!
+        raise Phronomy::Persistence::TransactionError, "Agent admission belongs to another execution context" unless @thread.equal?(Thread.current)
+      end
+    end
+  end
+end

data/lib/phronomy/agent/{lifecycle_contract/agent_already_exists_error.rb → agent_already_exists_error.rb}

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require_relative "../../common/error"
+require_relative "../common/error"
 
 module Phronomy
   class AgentAlreadyExistsError < Phronomy::Error; end

data/lib/phronomy/agent/{lifecycle_contract/agent_busy_error.rb → agent_busy_error.rb}

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require_relative "../../common/error"
+require_relative "../common/error"
 
 module Phronomy
   class AgentBusyError < Phronomy::Error; end

data/lib/phronomy/agent/agent_not_found_error.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require_relative "../persistence/errors"
+
+module Phronomy
+  # Only the requested Agent root is absent, not one of its referenced records.
+  # @api public
+  class AgentNotFoundError < Phronomy::Persistence::NotFoundError
+    attr_reader :agent_id
+
+    def initialize(agent_id:)
+      @agent_id = agent_id.to_s.dup.freeze
+      super("Agent not found: #{@agent_id}", code: "agent.not_found")
+    end
+  end
+end

data/lib/phronomy/agent/{lifecycle_contract/agent_purged_error.rb → agent_purged_error.rb}

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require_relative "../../common/error"
+require_relative "../common/error"
 
 module Phronomy
   class AgentPurgedError < Phronomy::Error; end

data/lib/phronomy/agent/agent_unloaded_error.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Phronomy
+  # An old Agent reference cannot act on a later incarnation of the same ID.
+  # @api public
+  class AgentUnloadedError < Phronomy::Error
+    attr_reader :agent_id
+
+    def initialize(agent_id:)
+      @agent_id = agent_id.to_s.dup.freeze
+      super("Agent #{@agent_id.inspect} has been unloaded", code: "agent.unloaded")
+    end
+  end
+end

data/lib/phronomy/agent/api/agent.rb

@@ -3,6 +3,17 @@
 module Phronomy
   module Agent
     StreamEvent = Data.define(:type, :payload)
+
+    # Own Agents acquired by the block, then attempt every release. A returned
+    # TaskResult is awaited and unwrapped; a plain value is returned unchanged.
+    # @yield [scope] the Runtime-bound owner of newly materialized Agents
+    # @yieldparam scope [Phronomy::Agent::Scope]
+    # @return [Object] the block value or resolved TaskResult value
+    # @raise [ScopeCleanupError] successful work whose Agent release failed
+    # @api public
+    def self.open_scope(&block)
+      Scope.send(:open, &block)
+    end
   end
 end
 
@@ -15,3 +26,5 @@ end
 # Durable Agent Recovery and Agent-incarnation event binding.
 require_relative "../recovery/recovery_support"
 require_relative "../recovery/recovery_coordinator"
+
+Phronomy::Agent::Base.prepend(Phronomy::Agent::LifetimeApi)

data/lib/phronomy/{recovery → agent/api}/execution_rehydration_required_error.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require_relative "../common/error"
+require_relative "../../common/error"
 
 module Phronomy
   class ExecutionRehydrationRequiredError < Phronomy::Error; end

data/lib/phronomy/agent/async_event_api.rb

@@ -12,6 +12,43 @@ module Phronomy
     # - approval notifications share the Agent listener as :approval_required;
     # - Recovery resolution uses resolve/resolve_async.
     module AsyncEventApi
+      def start_reserved_async(reservation:, input:, config: {})
+        __with_operation(async: true) do
+          unless reservation.is_a?(ReservedExecution) && reservation.agent_id == agent_id
+            raise ArgumentError, "reservation must belong to this Agent"
+          end
+          config = __invocation_config(_prepare_invocation_config(config, nil))
+          ExactExecution.start(agent: self, execution_id: reservation.execution_id, input: input,
+            config: config.merge(phronomy_reservation: reservation.correlation))
+        end
+      end
+
+      def resume_async(execution_id, config: {})
+        __with_operation(async: true) do
+          config = __invocation_config(_prepare_invocation_config(config, nil))
+          ExactExecution.start(agent: self, execution_id: execution_id, input: nil, config: config, resume_only: true)
+        end
+      end
+
+      def resume(execution_id, config: {})
+        __with_operation do
+          _check_event_loop_reentrancy(:resume, :resume_async)
+          resume_async(execution_id, config: config).wait_result
+        end
+      end
+
+      def cancel_async(execution_id)
+        __with_operation(async: true) do
+          __assert_live_agent!
+          environment = __execution_environment
+          environment.submit(on_full: :raise) do
+            requested = persistence.request_cancellation(agent_id: agent_id, execution_id: execution_id)
+            ExecutionCancellation.signal(execution_id, agent_id, environment: environment) if requested
+            persistence.observe_execution(agent_id: agent_id, execution_id: execution_id)
+          end
+        end
+      end
+
       def invoke(
         input,
         config: {},
@@ -19,15 +56,17 @@ module Phronomy
         **removed_options,
         &removed_block
       )
-        _reject_removed_invocation_listener_arguments!(removed_options, removed_block)
-        config = _prepare_invocation_config(config, invocation_context)
-        _check_event_loop_reentrancy(:invoke, :invoke_async)
-        _start_agent_operation(
-          input,
-          config: config,
-          mode: :invoke,
-          listener: _phronomy_event_listener
-        ).wait_result
+        __with_operation do
+          _reject_removed_invocation_listener_arguments!(removed_options, removed_block)
+          config = _prepare_invocation_config(config, invocation_context)
+          _check_event_loop_reentrancy(:invoke, :invoke_async)
+          _start_agent_operation(
+            input,
+            config: config,
+            mode: :invoke,
+            listener: _phronomy_event_listener
+          ).wait_result
+        end
       end
 
       def invoke_async(
@@ -37,14 +76,16 @@ module Phronomy
         **removed_options,
         &removed_block
       )
-        _reject_removed_invocation_listener_arguments!(removed_options, removed_block)
-        config = _prepare_invocation_config(config, invocation_context)
-        _start_agent_operation(
-          input,
-          config: config,
-          mode: :invoke,
-          listener: _phronomy_event_listener
-        )
+        __with_operation(async: true) do
+          _reject_removed_invocation_listener_arguments!(removed_options, removed_block)
+          config = _prepare_invocation_config(config, invocation_context)
+          _start_agent_operation(
+            input,
+            config: config,
+            mode: :invoke,
+            listener: _phronomy_event_listener
+          )
+        end
       end
 
       def stream(
@@ -54,16 +95,18 @@ module Phronomy
         **removed_options,
         &removed_block
       )
-        _reject_removed_invocation_listener_arguments!(removed_options, removed_block)
-        listener = _required_stream_listener!(:stream)
-        config = _prepare_invocation_config(config, invocation_context)
-        _check_event_loop_reentrancy(:stream, :stream_async)
-        _start_agent_operation(
-          input,
-          config: config,
-          mode: :stream,
-          listener: listener
-        ).wait_result
+        __with_operation do
+          _reject_removed_invocation_listener_arguments!(removed_options, removed_block)
+          listener = _required_stream_listener!(:stream)
+          config = _prepare_invocation_config(config, invocation_context)
+          _check_event_loop_reentrancy(:stream, :stream_async)
+          _start_agent_operation(
+            input,
+            config: config,
+            mode: :stream,
+            listener: listener
+          ).wait_result
+        end
       end
 
       def stream_async(
@@ -73,41 +116,47 @@ module Phronomy
         **removed_options,
         &removed_block
       )
-        _reject_removed_invocation_listener_arguments!(removed_options, removed_block)
-        listener = _required_stream_listener!(:stream_async)
-        config = _prepare_invocation_config(config, invocation_context)
-        _start_agent_operation(
-          input,
-          config: config,
-          mode: :stream,
-          listener: listener
-        )
+        __with_operation(async: true) do
+          _reject_removed_invocation_listener_arguments!(removed_options, removed_block)
+          listener = _required_stream_listener!(:stream_async)
+          config = _prepare_invocation_config(config, invocation_context)
+          _start_agent_operation(
+            input,
+            config: config,
+            mode: :stream,
+            listener: listener
+          )
+        end
       end
 
       def approve(execution_id, approval_request_id:, approved: true, config: {})
-        _check_event_loop_reentrancy(:approve, :approve_async)
-        approve_async(
-          execution_id,
-          approval_request_id: approval_request_id,
-          approved: approved,
-          config: config
-        ).wait_result
+        __with_operation do
+          _check_event_loop_reentrancy(:approve, :approve_async)
+          approve_async(
+            execution_id,
+            approval_request_id: approval_request_id,
+            approved: approved,
+            config: config
+          ).wait_result
+        end
       end
 
       def approve_async(execution_id, approval_request_id:, approved: true, config: {})
-        _reject_removed_generic_identity_keys!(config)
-        owner = Phronomy::Agent::ExecutionRegistry.existing_for(Phronomy::Runtime.instance)&.agent_execution_owner(execution_id)
-        coordinator = if owner&.agent&.equal?(self)
-          owner.coordinator
-        else
-          execution_coordinator_for(config)
+        __with_operation(async: true) do
+          _reject_removed_generic_identity_keys!(config)
+          owner = __execution_environment.existing_registry&.agent_execution_owner(execution_id)
+          coordinator = if owner&.agent&.equal?(self)
+            owner.coordinator
+          else
+            execution_coordinator_for(config)
+          end
+          coordinator.resume(
+            execution_id,
+            approval_request_id: approval_request_id,
+            approved: approved,
+            config: config
+          )
         end
-        coordinator.resume(
-          execution_id,
-          approval_request_id: approval_request_id,
-          approved: approved,
-          config: config
-        )
       end
 
       def resolve(
@@ -115,18 +164,20 @@ module Phronomy
         expected_execution_revision:,
         subject:,
         outcome:,
-        result: Phronomy::Recovery::MISSING,
-        error: Phronomy::Recovery::MISSING
+        result: Phronomy::Agent::RecoveryRules::MISSING,
+        error: Phronomy::Agent::RecoveryRules::MISSING
       )
-        _check_event_loop_reentrancy(:resolve, :resolve_async)
-        resolve_async(
-          execution_id,
-          expected_execution_revision: expected_execution_revision,
-          subject: subject,
-          outcome: outcome,
-          result: result,
-          error: error
-        ).wait_result
+        __with_operation do
+          _check_event_loop_reentrancy(:resolve, :resolve_async)
+          resolve_async(
+            execution_id,
+            expected_execution_revision: expected_execution_revision,
+            subject: subject,
+            outcome: outcome,
+            result: result,
+            error: error
+          ).wait_result
+        end
       end
 
       def resolve_async(
@@ -134,41 +185,26 @@ module Phronomy
         expected_execution_revision:,
         subject:,
         outcome:,
-        result: Phronomy::Recovery::MISSING,
-        error: Phronomy::Recovery::MISSING
+        result: Phronomy::Agent::RecoveryRules::MISSING,
+        error: Phronomy::Agent::RecoveryRules::MISSING
       )
-        Phronomy::Agent::RecoveryCoordinator.new(self).resolve(
-          execution_id,
-          expected_execution_revision: expected_execution_revision,
-          subject: subject,
-          outcome: outcome,
-          result: result,
-          error: error
-        )
+        __with_operation(async: true) do
+          Phronomy::Agent::RecoveryCoordinator.new(self).resolve(
+            execution_id,
+            expected_execution_revision: expected_execution_revision,
+            subject: subject,
+            outcome: outcome,
+            result: result,
+            error: error
+          )
+        end
       end
 
       private
 
-      # Framework-private execution-local event routing. This is intentionally
-      # not a public compatibility path for invoke_async(..., on_event:).
-      def __invoke_async_with_event_sink(
-        input,
-        on_event:, config: {},
-        invocation_context: nil
-      )
-        raise ArgumentError, "on_event is required" unless on_event
-
-        config = _prepare_invocation_config(config, invocation_context)
-        _start_agent_operation(
-          input,
-          config: config,
-          mode: :invoke,
-          listener: on_event
-        )
-      end
-
       def _start_agent_operation(input, config:, mode:, listener:)
-        config = _snapshot_durable_context(config)
+        config = __invocation_config(_snapshot_durable_context(config))
+        @_phronomy_execution_wiring = config.dup.freeze
         approval = _approval_configuration_snapshot(nil)
         execution_coordinator_for(config).start(
           input,
@@ -220,14 +256,7 @@ module Phronomy
         @execution_coordinator ||= Agent::ExecutionCoordinator.new(self)
       end
 
-      def execution_coordinator_for(config)
-        multi_agent = config.key?(:phronomy_handoff_bindings) ||
-          config.key?(:phronomy_handoff_context)
-        return execution_coordinator unless multi_agent
-
-        @multi_agent_execution_coordinator ||=
-          Phronomy::Agent::HandoffExecutionCoordinator.new(self)
-      end
+      def execution_coordinator_for(_config) = execution_coordinator
     end
   end
 end