phronomy 0.28.0 → 0.29.0

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

@@ -93,7 +93,7 @@ module Phronomy
       )
         @agent.send(:__assert_live_agent!)
         @agent.send(:_reject_removed_generic_identity_keys!, config)
-        result_task = Phronomy::TaskResult.deferred(name: "agent-#{@agent.agent_id}-#{mode}")
+        result_task = OperationResult.new(agent: @agent, name: "agent-#{@agent.agent_id}-#{mode}")
         controls = Phronomy::InvocationControls.attach(result_task,
           invocation_context: config[:invocation_context],
           cancellation_token: config[:cancellation_token])
@@ -127,9 +127,8 @@ module Phronomy
       )
         @agent.send(:__assert_live_agent!)
         @agent.send(:_reject_removed_generic_identity_keys!, config)
-        result_task = Phronomy::TaskResult.deferred(
-          name: "agent-approval-resume:#{execution_id}"
-        )
+        result_task = OperationResult.new(agent: @agent,
+          name: "agent-approval-resume:#{execution_id}")
         command = ResumeCommand.new(
           coordinator: self,
           execution_id: execution_id.to_s.freeze,
@@ -269,7 +268,7 @@ module Phronomy
       def begin_start_on_event_loop(request)
         environment = @agent.__execution_environment
         request.controls.check_start!
-        root = @agent.agent_root
+        root = @agent.send(:__root_for_operation)
         if root.lifecycle_status == :closed
           deliver_start_failure_on_event_loop(
             request,
@@ -298,6 +297,7 @@ module Phronomy
           @initial_preparation.prepare(operation)
         end
         submitted = true
+        request.result_task.track(task) if request.result_task.respond_to?(:track)
         task.on_complete do |result, error|
           ready = InitialPreparationReady.new(
             coordinator: self,
@@ -519,7 +519,7 @@ module Phronomy
 
         operation = InitialPreparation::RecoveryCommand.new(
           execution: execution,
-          root: @agent.agent_root,
+          root: @agent.send(:__root_for_operation),
           journal_records: @agent.send(:_journal_records_snapshot)
         )
         task = environment.submit(on_full: :raise) do
@@ -717,7 +717,7 @@ module Phronomy
           execution_id: state.execution_id,
           fsm_session_id: fsm_session_id.to_s.freeze,
           expected_execution_revision: state.execution.execution_revision,
-          root: @agent.agent_root,
+          root: @agent.send(:__root_for_operation),
           journal_records: @agent.send(:_journal_records_snapshot),
           execution: state.execution,
           base_manifest: state.base_manifest,
@@ -739,7 +739,7 @@ module Phronomy
           execution_id: state.execution_id,
           fsm_session_id: fsm_session_id.to_s.freeze,
           expected_execution_revision: state.execution.execution_revision,
-          root: @agent.agent_root,
+          root: @agent.send(:__root_for_operation),
           execution: state.execution,
           runtime_snapshot: invocation.runtime_snapshot,
           tool_batch_snapshot: tool_batch_snapshot,
@@ -921,6 +921,7 @@ module Phronomy
           @approval_resume_commit.commit(operation)
         end
         submitted = true
+        request.result_task.track(task) if request.result_task.respond_to?(:track)
         task.on_complete do |result, error|
           ready = ResumeCommitReady.new(
             coordinator: self,
@@ -953,7 +954,7 @@ module Phronomy
         ResumeCommitCommand.new(
           execution_id: state.execution_id,
           expected_execution_revision: state.execution.execution_revision,
-          root: @agent.agent_root,
+          root: @agent.send(:__root_for_operation),
           execution: state.execution,
           approval_request_id: request.approval_request_id,
           approved: request.approved,
@@ -1254,7 +1255,7 @@ module Phronomy
 
         operation = build_terminal_operation(
           execution: state.execution,
-          root: @agent.agent_root,
+          root: @agent.send(:__root_for_operation),
           journal_records: @agent.send(:_journal_records_snapshot),
           invocation: invocation,
           source_error: source_error,
@@ -1338,6 +1339,7 @@ module Phronomy
           # worker boundary. TaskResult/listener delivery state stays outside it.
           @outcome_committer.commit_outcome(operation)
         end
+        delivery.result_task.track(task) if delivery.result_task.respond_to?(:track)
         task.on_complete do |outcome, error|
           ready = TerminalCommitReady.new(
             coordinator: self,
@@ -1440,7 +1442,7 @@ module Phronomy
         if operation.execution.metadata["reservation"] || operation.execution.metadata["execution_extension"]
           release_terminal_ownership(environment, operation.execution_id, state)
           environment.registry.take_agent_completion_waiters(operation.execution_id, fallback: delivery.result_task).each do |task|
-            task.fail(ready.error)
+            fail_task(task, ready.error)
           end
           return
         end
@@ -1477,7 +1479,7 @@ module Phronomy
         delivery = ready.delivery
         outcome = ready.outcome
         release_terminal_ownership(environment, operation.execution_id, state)
-        environment.registry.take_agent_completion_waiters(operation.execution_id, fallback: delivery.result_task).each { |task| task.fail(outcome.error) }
+        environment.registry.take_agent_completion_waiters(operation.execution_id, fallback: delivery.result_task).each { |task| fail_task(task, outcome.error) }
       end
 
       def suspend_execution_on_event_loop(ready, state, environment)
@@ -1501,7 +1503,7 @@ module Phronomy
           outcome.result
         )
         Array(state&.invocation&.config&.fetch(:phronomy_exact_observers, [])).each do |task|
-          task.fail(Phronomy::ExecutionRehydrationRequiredError.new("Execution #{operation.execution_id} requires approval"))
+          fail_task(task, Phronomy::ExecutionRehydrationRequiredError.new("Execution #{operation.execution_id} requires approval"))
         end
       end
 
@@ -1695,6 +1697,7 @@ module Phronomy
         end
         if execution_error
           if execution_error.is_a?(Phronomy::CancellationError)
+            result_task.finish_operation! if result_task.respond_to?(:finish_operation!)
             result_task.cancel!(execution_error)
           else
             fail_task(result_task, execution_error)

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

@@ -187,7 +187,7 @@ module Phronomy
       def encode_failure(tx, operation, error)
         current = operation.execution
         encoded_records, call_records = encode_runtime_records(tx, operation, context_candidate: false)
-        error_ref = tx.contents.put_json("class" => error.class.name, "message" => error.message)
+        error_ref = tx.contents.put_json(Phronomy::Error.diagnostic(error))
         terminal_status = ExecutionFailure.status_for(error)
         records = failure_records(operation, encoded_records, terminal_status, error_ref)
         failed = current.with(

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

@@ -262,10 +262,7 @@ module Phronomy
         translated_error = error
         failed = next_root = appended = nil
         @persistence.transaction do |tx|
-          error_ref = tx.contents.put_json(
-            "class" => translated_error.class.name,
-            "message" => translated_error.message
-          )
+          error_ref = tx.contents.put_json(Phronomy::Error.diagnostic(translated_error))
           status = ExecutionFailure.status_for(translated_error)
           records = preparation_failure_records(execution, root, status, error_ref)
           appended = tx.journals.append(

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

@@ -29,10 +29,7 @@ module Phronomy
           output_ref = assistant_output_ref(tx, outcome)
           assistant_ref = assistant_message_ref(tx, outcome)
           error_ref = if call_error
-            tx.contents.put_json(
-              "class" => call_error.class.name,
-              "message" => call_error.message
-            )
+            tx.contents.put_json(Phronomy::Error.diagnostic(call_error))
           end
           usage_ref = if outcome && outcome.usage.to_h.values.any? { |value| !value.nil? }
             tx.contents.put_json(json_value(outcome.usage.to_h))

data/lib/phronomy/agent/filterable.rb

@@ -92,9 +92,11 @@ module Phronomy
       # @return [self]
       # @api public
       def add_input_filter(filter)
-        @_instance_input_filters ||= []
-        @_instance_input_filters << _resolve_filter(filter)
-        self
+        __with_operation do
+          @_instance_input_filters ||= []
+          @_instance_input_filters << _resolve_filter(filter)
+          self
+        end
       end
 
       # Registers an output filter on this instance.
@@ -105,9 +107,11 @@ module Phronomy
       # @return [self]
       # @api public
       def add_output_filter(filter)
-        @_instance_output_filters ||= []
-        @_instance_output_filters << _resolve_filter(filter)
-        self
+        __with_operation do
+          @_instance_output_filters ||= []
+          @_instance_output_filters << _resolve_filter(filter)
+          self
+        end
       end
 
       # Registers a tool result filter on this instance.
@@ -125,16 +129,18 @@ module Phronomy
       # @return [self]
       # @api public
       def add_tool_result_filter(tool_class_or_filter, filter = nil)
-        if filter.nil?
-          # Single-argument form: apply to all tools.
-          @_instance_tool_result_filters ||= []
-          @_instance_tool_result_filters << _resolve_filter(tool_class_or_filter)
-        else
-          # Two-argument form: scoped to one tool class.
-          @_scoped_tool_result_filters ||= {}
-          (@_scoped_tool_result_filters[tool_class_or_filter] ||= []) << _resolve_filter(filter)
+        __with_operation do
+          if filter.nil?
+            # Single-argument form: apply to all tools.
+            @_instance_tool_result_filters ||= []
+            @_instance_tool_result_filters << _resolve_filter(tool_class_or_filter)
+          else
+            # Two-argument form: scoped to one tool class.
+            @_scoped_tool_result_filters ||= {}
+            (@_scoped_tool_result_filters[tool_class_or_filter] ||= []) << _resolve_filter(filter)
+          end
+          self
         end
-        self
       end
 
       private

data/lib/phronomy/agent/lifecycle/lifetime_api.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    # Public admission boundaries. The explicit operation capability belongs to
+    # C04, including queued work and domain completion after logical cancellation.
+    # @api private
+    module LifetimeApi
+      # Releases only the Runtime incarnation; durable state and Store stay intact.
+      # @return [TaskResult<Boolean>]
+      # @api public
+      def unload_async
+        return Phronomy::TaskResult.completed(false) if @_phronomy_runtime_owner_state == :unloaded
+
+        __assert_agent_accessible!
+        transition, start = __execution_environment.ownership.reserve_unload(self)
+        start ? transition.start : transition.result
+      rescue => error
+        Phronomy::TaskResult.failed(error)
+      end
+
+      # A timeout stops this wait, never the accepted release.
+      # @return [Boolean]
+      # @api public
+      def unload!(timeout: nil)
+        _check_event_loop_reentrancy(:unload!, :unload_async)
+        unload_async.wait_result(timeout: timeout)
+      end
+
+      private
+
+      def __with_operation(async: false, read_only: false)
+        lease = __acquire_operation!(read_only: read_only)
+        followed = false
+        value = yield
+        if async && lease
+          lease.follow(value)
+          followed = true
+        end
+        value
+      rescue Phronomy::AgentUnloadedError, Phronomy::AgentBusyError, Phronomy::RuntimeShutdownError => error
+        raise unless async
+        Phronomy::TaskResult.failed(error)
+      ensure
+        lease&.release unless followed
+      end
+
+      # Accepted C04 commands carry their admission/operation capability. Their
+      # continuations read the snapshot without entering the public admission gate.
+      def __root_for_operation
+        __assert_agent_accessible!
+        @root
+      end
+
+      def __acquire_operation!(read_only: false)
+        __assert_agent_accessible!
+        return nil if @_phronomy_runtime_owner_state == :constructing
+
+        __execution_environment.ownership.acquire_operation(self, read_only: read_only)
+      end
+
+      def __mark_unloaded!
+        @_phronomy_runtime_owner_state = :unloaded
+        @root = nil
+        @_phronomy_journal_records = [].freeze
+        @_phronomy_event_listener = nil
+        @_phronomy_execution_wiring = {}.freeze
+        @execution_coordinator = nil
+        @tool_approval_policy = @before_llm_input = nil
+        @_instance_input_filters = @_instance_output_filters = nil
+        @_instance_tool_result_filters = @_scoped_tool_result_filters = nil
+        @initial_retention = nil
+      end
+    end
+  end
+end

data/lib/phronomy/agent/lifecycle/operation_lease.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    # C04 capability for accepted work. Never inferred from the current thread.
+    # @api private
+    class OperationLease
+      def initialize(registry, agent, token)
+        @registry, @agent, @token = registry, agent, token
+        @mutex = Mutex.new
+      end
+
+      def release
+        ownership = @mutex.synchronize do
+          next unless @registry
+          current = [@registry, @agent, @token]
+          @registry = @agent = @token = nil
+          current
+        end
+        ownership&.first&.release_operation(ownership[1], ownership[2])
+      end
+
+      def follow(task)
+        if task.respond_to?(:on_physical_complete)
+          task.on_physical_complete { release }
+        else
+          task.on_complete { |_value, _error| release }
+        end
+        task
+      end
+    end
+  end
+end

data/lib/phronomy/agent/lifecycle/operation_result.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    # Logical cancellation of a public handle does not release Agent ownership.
+    # Only the domain runner acknowledges the end of its accepted operation.
+    # @api private
+    class OperationResult < Phronomy::Concurrency::PhysicalCompletionTask
+      def initialize(agent:, name:)
+        super(name: name)
+        @operation_lease = agent.send(:__acquire_operation!)
+        @lifetime_mutex = Mutex.new
+        @work = 0
+        @finished = false
+        @released = false
+      end
+
+      def finish_operation!
+        @lifetime_mutex.synchronize { @finished = true }
+        release_if_quiet
+      end
+
+      def track(task)
+        @lifetime_mutex.synchronize { @work += 1 }
+        task.on_physical_complete do
+          @lifetime_mutex.synchronize { @work -= 1 }
+          release_if_quiet
+        end
+        task
+      end
+
+      def settle(value = nil, error: nil)
+        finish_operation!
+        error ? fail(error) : complete(value)
+      end
+
+      private
+
+      def release_if_quiet
+        released = @lifetime_mutex.synchronize do
+          next unless @finished && @work.zero? && !@released
+          @released = true
+          current = @operation_lease
+          @operation_lease = nil
+          [current]
+        end
+        return unless released
+        released.first&.release
+        mark_physical_complete!
+      end
+    end
+  end
+end

data/lib/phronomy/agent/lifecycle/ownership_registry.rb

@@ -25,12 +25,14 @@ module Phronomy
         @mutex = Mutex.new
         @condition = ConditionVariable.new
         @entries = {}
+        @scope_owners = {}
+        @operations = {}
         @state = :running
       end
 
-      def create(agent_id, expected_class:)
+      def create(agent_id, expected_class:, scope_owner: nil)
         key = normalize_agent_id(agent_id)
-        token = reserve_create!(key)
+        token = reserve_create!(key, scope_owner: scope_owner)
 
         begin
           agent = yield(@environment)
@@ -59,7 +61,7 @@ module Phronomy
         )
       end
 
-      def load(agent_id, expected_class:)
+      def load(agent_id, expected_class:, scope_owner: nil)
         key = normalize_agent_id(agent_id)
         token = nil
 
@@ -67,9 +69,14 @@ module Phronomy
           existing = @mutex.synchronize do
             ensure_running!
             entry = @entries[key]
+            if scope_owner && entry && !@scope_owners[key].equal?(scope_owner)
+              raise Phronomy::AgentBusyError, "Agent #{key.inspect} belongs to another live owner"
+            end
             case entry&.state
             when :live
               entry.agent
+            when :unloading
+              raise Phronomy::AgentBusyError, "Agent #{key.inspect} is unloading"
             when :constructing, :purging
               @condition.wait(@mutex)
               :retry
@@ -78,6 +85,7 @@ module Phronomy
             when nil
               token = Object.new.freeze
               @entries[key] = Entry.new(state: :constructing, agent: nil, token: token)
+              @scope_owners[key] = scope_owner if scope_owner
               nil
             # :nocov:
             else
@@ -119,8 +127,8 @@ module Phronomy
           when :recovery_required
             raise ownership_recovery_error(key)
           # :nocov:
-          when :purging
-            raise Phronomy::Error, "Agent #{key.inspect} is being purged"
+          when :purging, :unloading
+            raise Phronomy::AgentBusyError, "Agent #{key.inspect} is #{entry.state}"
             # :cover:
           end
         end
@@ -129,13 +137,77 @@ module Phronomy
         validate_expected_class!(agent, expected_class, key)
       end
 
+      # Admission and lifetime transitions share this mutex. No Runtime or Store
+      # operation is called while it is held.
+      def acquire_operation(agent, read_only: false)
+        token = Object.new.freeze
+        @mutex.synchronize do
+          ensure_running! unless read_only && @state == :draining
+          entry = @entries[agent.agent_id]
+          if entry&.agent&.equal?(agent) && entry.state == :unloading
+            raise Phronomy::AgentBusyError, "Agent #{agent.agent_id.inspect} is unloading"
+          end
+          unless entry&.state == :live && entry.agent.equal?(agent)
+            raise Phronomy::RuntimeShutdownError, "Agent is no longer the live Runtime owner"
+          end
+          (@operations[agent] ||= {})[token] = true
+        end
+        OperationLease.new(self, agent, token)
+      end
+
+      def release_operation(agent, token)
+        @mutex.synchronize do
+          operations = @operations[agent]
+          operations&.delete(token)
+          @operations.delete(agent) if operations && operations.empty?
+          @condition.broadcast
+        end
+        true
+      end
+
+      # Returns the already accepted transition for duplicate callers.
+      def reserve_unload(agent)
+        @mutex.synchronize do
+          ensure_running!
+          entry = @entries[agent.agent_id]
+          if entry&.state == :unloading && entry.agent.equal?(agent)
+            return [entry.token, false]
+          end
+          unless entry&.state == :live && entry.agent.equal?(agent)
+            raise Phronomy::RuntimeShutdownError, "Agent is no longer the live Runtime owner"
+          end
+          assert_no_operations!(agent)
+          transition = UnloadTransition.new(agent: agent, environment: @environment, ownership: self)
+          @entries[agent.agent_id] = Entry.new(state: :unloading, agent: agent, token: transition)
+          [transition, true]
+        end
+      end
+
+      def finish_unload(agent, transition, success:)
+        @mutex.synchronize do
+          entry = @entries[agent.agent_id]
+          unless entry&.state == :unloading && entry.agent.equal?(agent) && entry.token.equal?(transition)
+            raise Phronomy::RuntimeShutdownError, "Agent unload reservation is no longer authoritative"
+          end
+          if success
+            agent.send(:__mark_unloaded!)
+            @entries.delete(agent.agent_id)
+            @scope_owners.delete(agent.agent_id)
+          else
+            @entries[agent.agent_id] = Entry.new(state: :live, agent: agent, token: nil)
+          end
+          @condition.broadcast
+        end
+        true
+      end
+
       def owned?(agent)
         return false unless agent
 
         key = normalize_agent_id(agent.agent_id)
         @mutex.synchronize do
           entry = @entries[key]
-          entry&.state == :live && entry.agent.equal?(agent)
+          %i[live unloading].include?(entry&.state) && entry.agent.equal?(agent)
         end
       rescue ArgumentError
         false
@@ -151,9 +223,13 @@ module Phronomy
           ensure_running!
           entry = @entries[key]
           unless entry&.state == :live && entry.agent.equal?(agent)
+            if entry&.state == :unloading && entry.agent.equal?(agent)
+              raise Phronomy::AgentBusyError, "Agent #{key.inspect} is unloading"
+            end
             raise Phronomy::RuntimeShutdownError,
               "Agent #{key.inspect} is not the live owner in this Runtime"
           end
+          assert_no_operations!(agent)
           @entries[key] = Entry.new(state: :purging, agent: agent, token: token)
         end
         agent.send(:__mark_purging!, @environment)
@@ -167,6 +243,7 @@ module Phronomy
           validate_purge_entry!(entry, agent, token, key)
           agent.send(:__mark_purged!, @environment)
           @entries.delete(key)
+          @scope_owners.delete(key)
           @condition.broadcast
         end
         true
@@ -215,7 +292,7 @@ module Phronomy
       # ownership transition that is still actively changing state must settle.
       def wait_until_idle(deadline)
         @mutex.synchronize do
-          while @entries.values.any? { |entry| %i[constructing purging].include?(entry.state) }
+          while @entries.values.any? { |entry| %i[constructing purging unloading].include?(entry.state) }
             remaining = deadline - monotonic_now
             # :nocov:
             return false if remaining <= 0
@@ -231,6 +308,8 @@ module Phronomy
           @state = :terminated
           owned = @entries.values.filter_map(&:agent).uniq
           @entries.clear
+          @scope_owners.clear
+          @operations.clear
           @condition.broadcast
           owned
         end
@@ -240,17 +319,22 @@ module Phronomy
 
       private
 
-      def reserve_create!(key)
+      def reserve_create!(key, scope_owner: nil)
         token = Object.new.freeze
         @mutex.synchronize do
           ensure_running!
           if (entry = @entries[key])
             raise ownership_recovery_error(key) if entry.state == :recovery_required
 
+            if scope_owner
+              raise Phronomy::AgentBusyError, "Agent #{key.inspect} already has a Runtime owner"
+            end
+
             raise Phronomy::AgentAlreadyExistsError,
               "Agent #{key.inspect} already exists in this Runtime (#{entry.state})"
           end
           @entries[key] = Entry.new(state: :constructing, agent: nil, token: token)
+          @scope_owners[key] = scope_owner if scope_owner
         end
         token
       end
@@ -291,6 +375,7 @@ module Phronomy
           # :nocov:
           if entry&.state == :constructing && entry.token.equal?(token)
             @entries.delete(key)
+            @scope_owners.delete(key)
             @condition.broadcast
           end
           # :cover:
@@ -353,6 +438,12 @@ module Phronomy
         # :cover:
       end
 
+      def assert_no_operations!(agent)
+        return unless @operations[agent]&.any?
+
+        raise Phronomy::AgentBusyError, "Agent #{agent.agent_id.inspect} still has accepted operations"
+      end
+
       def monotonic_now
         Process.clock_gettime(Process::CLOCK_MONOTONIC)
       end