phronomy 0.28.0 → 0.29.0

data/gemfiles/http_minimum.gemfile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+eval_gemfile "mcp_1_0.gemfile"
+gem "faraday", "= 2.1.0"
+gem "webmock", require: false

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/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/agent/async_event_api.rb

@@ -13,31 +13,39 @@ module Phronomy
     # - Recovery resolution uses resolve/resolve_async.
     module AsyncEventApi
       def start_reserved_async(reservation:, input:, config: {})
-        unless reservation.is_a?(ReservedExecution) && reservation.agent_id == agent_id
-          raise ArgumentError, "reservation must belong to this Agent"
+        __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
-        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
 
       def resume_async(execution_id, config: {})
-        config = __invocation_config(_prepare_invocation_config(config, nil))
-        ExactExecution.start(agent: self, execution_id: execution_id, input: nil, config: config, resume_only: true)
+        __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: {})
-        _check_event_loop_reentrancy(:resume, :resume_async)
-        resume_async(execution_id, config: config).wait_result
+        __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)
-        __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)
+        __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
 
@@ -48,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(
@@ -66,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(
@@ -83,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(
@@ -102,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_current&.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(
@@ -147,15 +167,17 @@ module Phronomy
         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(
@@ -166,14 +188,16 @@ module Phronomy
         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

data/lib/phronomy/agent/base.rb

@@ -292,10 +292,14 @@ module Phronomy
       # @api private
       def __invocation_config(config) = config
 
-      def knowledge_snapshot = persistence.knowledge_snapshot(agent_id: agent_id)
+      def knowledge_snapshot
+        __with_operation { persistence.knowledge_snapshot(agent_id: agent_id) }
+      end
 
       # Listener inheritance is an explicit orchestration choice, not a private getter.
-      def event_listener = _phronomy_event_listener
+      def event_listener
+        __with_operation(read_only: true) { _phronomy_event_listener }
+      end
 
       attr_reader :agent_id, :persistence
 
@@ -371,65 +375,81 @@ module Phronomy
       end
 
       def agent_root
-        __assert_agent_accessible!
-        @root
+        __with_operation(read_only: true) do
+          __assert_agent_accessible!
+          @root
+        end
       end
 
       def journal_projection
-        __assert_agent_accessible!
-        Agent::JournalProjection.new(
-          agent_root: @root,
-          records: _journal_records_snapshot
-        )
+        __with_operation(read_only: true) do
+          __assert_agent_accessible!
+          Agent::JournalProjection.new(
+            agent_root: @root,
+            records: _journal_records_snapshot
+          )
+        end
       end
 
       def transcript
-        journal_projection.transcript_records
+        __with_operation(read_only: true) do
+          journal_projection.transcript_records
+        end
       end
 
       def clear_transcript!
-        mutate_context!(:transcript_cleared) do |root|
-          root.with(
-            agent_revision: root.agent_revision + 1,
-            context_revision: root.context_revision + 1,
-            transcript_generation: root.transcript_generation + 1
-          )
+        __with_operation do
+          mutate_context!(:transcript_cleared) do |root|
+            root.with(
+              agent_revision: root.agent_revision + 1,
+              context_revision: root.context_revision + 1,
+              transcript_generation: root.transcript_generation + 1
+            )
+          end
         end
       end
 
       def clear_knowledge!
-        mutate_context!(:knowledge_cleared) do |root|
-          root.with(
-            agent_revision: root.agent_revision + 1,
-            context_revision: root.context_revision + 1
-          )
+        __with_operation do
+          mutate_context!(:knowledge_cleared) do |root|
+            root.with(
+              agent_revision: root.agent_revision + 1,
+              context_revision: root.context_revision + 1
+            )
+          end
         end
       end
 
       def add_knowledge(content, metadata: {})
-        __assert_live_agent!
-        current = agent_root
-        update = state_writer.add_knowledge(root: current, content: content, metadata: metadata)
-        apply_state_update(update)
-        self
+        __with_operation do
+          __assert_live_agent!
+          current = agent_root
+          update = state_writer.add_knowledge(root: current, content: content, metadata: metadata)
+          apply_state_update(update)
+          self
+        end
       end
 
       def reset_context!
-        mutate_context!(:context_reset) do |root|
-          root.with(
-            agent_revision: root.agent_revision + 1,
-            context_revision: root.context_revision + 1,
-            transcript_generation: root.transcript_generation + 1
-          )
+        __with_operation do
+          mutate_context!(:context_reset) do |root|
+            root.with(
+              agent_revision: root.agent_revision + 1,
+              context_revision: root.context_revision + 1,
+              transcript_generation: root.transcript_generation + 1
+            )
+          end
         end
       end
 
       def close!
-        mutate_context!(:agent_closed, context_affecting: false) do |root|
-          root.with(
-            agent_revision: root.agent_revision + 1,
-            lifecycle_status: :closed
-          )
+        __with_operation do
+          mutate_context!(:agent_closed, context_affecting: false) do |root|
+            root.with(
+              agent_revision: root.agent_revision + 1,
+              lifecycle_status: :closed
+            )
+          end
         end
       end
 
@@ -544,7 +564,7 @@ module Phronomy
 
       # @api private
       def __release_runtime_owner!(runtime)
-        return self if @_phronomy_runtime_owner_state == :purged
+        return self if %i[purged unloaded].include?(@_phronomy_runtime_owner_state)
         return self unless @_phronomy_runtime_owner.equal?(runtime)
 
         @_phronomy_runtime_owner_state = :released
@@ -579,7 +599,12 @@ module Phronomy
         if load_existing
           root = records = nil
           @persistence.transaction do |tx|
-            root = tx.agents.load(@agent_id)
+            begin
+              root = tx.agents.load(@agent_id)
+            rescue Phronomy::Persistence::NotFoundError => error
+              raise if error.is_a?(Phronomy::AgentNotFoundError)
+              raise Phronomy::AgentNotFoundError.new(agent_id: @agent_id), cause: error
+            end
             records = tx.journals.read(
               @agent_id,
               limit: root.journal_position
@@ -656,11 +681,13 @@ module Phronomy
       public
 
       def tool_approval_policy(&block)
-        __assert_live_agent!
-        raise ArgumentError, "tool_approval_policy requires a block" unless block
+        __with_operation do
+          __assert_live_agent!
+          raise ArgumentError, "tool_approval_policy requires a block" unless block
 
-        _approval_configuration_mutex.synchronize { @tool_approval_policy = block }
-        self
+          _approval_configuration_mutex.synchronize { @tool_approval_policy = block }
+          self
+        end
       end
 
       private
@@ -671,6 +698,8 @@ module Phronomy
           true
         when :purged
           raise Phronomy::AgentPurgedError, "Agent #{agent_id.inspect} has been purged"
+        when :unloaded
+          raise Phronomy::AgentUnloadedError.new(agent_id: agent_id)
         when :purging
           raise Phronomy::Error, "Agent #{agent_id.inspect} is being purged"
         when :recovery_required
@@ -728,10 +757,12 @@ module Phronomy
       end
 
       def _complete_result_task(task, result)
+        task.finish_operation! if task.respond_to?(:finish_operation!)
         task.complete(result)
       end
 
       def _fail_result_task(task, error)
+        task.finish_operation! if task.respond_to?(:finish_operation!)
         task.fail(error)
       end
 

data/lib/phronomy/agent/before_llm_input.rb

@@ -19,7 +19,13 @@ module Phronomy
         def _before_llm_input = @before_llm_input
       end
 
-      attr_accessor :before_llm_input
+      def before_llm_input
+        __with_operation(read_only: true) { @before_llm_input }
+      end
+
+      def before_llm_input=(value)
+        __with_operation { @before_llm_input = value }
+      end
 
       private
 

data/lib/phronomy/agent/execution/exact_execution.rb

@@ -18,7 +18,7 @@ module Phronomy
         @agent, @id, @input, @config = agent, execution_id.to_s.freeze, input, config.freeze
         @resume_only = resume_only
         @environment = @agent.__execution_environment
-        @completion = Phronomy::TaskResult.deferred(name: "exact-execution:#{@id}")
+        @completion = OperationResult.new(agent: @agent, name: "exact-execution:#{@id}")
       end
 
       def start
@@ -43,13 +43,14 @@ module Phronomy
             [:absent, nil]
           end
         end
+        @completion.track(preparation)
         preparation.on_complete do |prepared, error|
           if error
-            @completion.fail(error)
+            @completion.settle(error: error)
           else
             disposition, result = prepared
             case disposition
-            when :terminal then @completion.complete(result)
+            when :terminal then @completion.settle(result)
             when :absent
               source = @agent.send(:_start_agent_operation, @input,
                 config: @config.merge(phronomy_reserved_execution_id: @id, phronomy_exact_observers: [@completion].freeze),
@@ -58,15 +59,15 @@ module Phronomy
             when :active
               command = Wait.new(coordinator: self, agent: @agent, execution_id: @id)
               posted = @environment.registry.post(command, completion: @completion)
-              @completion.fail(Phronomy::RuntimeShutdownError.new("Exact execution observer rejected")) unless posted
+              @completion.settle(error: Phronomy::RuntimeShutdownError.new("Exact execution observer rejected")) unless posted
             end
           end
         rescue => failure
-          @completion.fail(failure)
+          @completion.settle(error: failure)
         end
         @completion
       rescue => failure
-        @completion.fail(failure)
+        @completion.settle(error: failure)
         @completion
       end
 
@@ -101,7 +102,7 @@ module Phronomy
         waiter.on_complete { |_result, failure| reconcile(failure) }
         @environment.registry.register_agent_completion_waiter(@id, waiter)
       rescue => failure
-        @completion.fail(failure)
+        @completion.settle(error: failure)
       end
 
       private
@@ -157,11 +158,12 @@ module Phronomy
             ))
           end
         end
+        @completion.track(task)
         task.on_complete do |result, error|
-          error ? @completion.fail(error) : @completion.complete(result)
+          error ? @completion.settle(error: error) : @completion.settle(result)
         end
       rescue => error
-        @completion.fail(error)
+        @completion.settle(error: error)
       end
 
       def materialize(execution)