phronomy 0.22.0 → 0.23.0

data/lib/phronomy/agent/base.rb

@@ -40,17 +40,6 @@ module Phronomy
       private_constant :APPROVAL_CONFIGURATION_INIT_MUTEX
 
       class << self
-        # Sets or reads the LLM model identifier for this agent.
-        # When called without an argument, returns the stored model or the
-        # global default from {Phronomy.configuration}.
-        #
-        # @param name [String, nil] model identifier (e.g. "gpt-4o", "claude-3-5-sonnet")
-        # @return [String, nil] the model name when used as a reader
-        # @example
-        #   class MyAgent < Phronomy::Agent::Base
-        #     model "gpt-4o"
-        #   end
-        # @api public
         def model(name = nil)
           if name
             @model = name
@@ -59,22 +48,6 @@ module Phronomy
           end
         end
 
-        # Sets or reads the system instructions for this agent.
-        # Accepts a String, a {Phronomy::Agent::Context::Instruction::PromptTemplate}, or a block (Proc).
-        # When used as a reader (no argument, no block), returns the stored value.
-        #
-        # @param text [String, Phronomy::Agent::Context::Instruction::PromptTemplate, nil]
-        # @yield optionally provide instructions as a block
-        # @return [String, Phronomy::Agent::Context::Instruction::PromptTemplate, Proc, nil]
-        # @example String instructions
-        #   class MyAgent < Phronomy::Agent::Base
-        #     instructions "You are a helpful assistant."
-        #   end
-        # @example Block instructions
-        #   class MyAgent < Phronomy::Agent::Base
-        #     instructions { |input| "Answer in #{input[:lang]}." }
-        #   end
-        # @api public
         def instructions(text = nil, &block)
           if text || block_given?
             @instructions = text || block
@@ -84,19 +57,6 @@ module Phronomy
           end
         end
 
-        # Registers tool classes for this agent.
-        #
-        # The setter accepts one Hash mapping each Tool class to an explicit alias
-        # name (String) or nil (use the Tool's own name). Calling without an
-        # argument returns the registered Tool classes.
-        #
-        # @example
-        #   tools(
-        #     Weather::SearchTool => "weather_search",
-        #     Places::SearchTool  => "places_search",
-        #     CurrentTimeTool     => nil
-        #   )
-        # @api public
         def tools(definitions = nil)
           if definitions.nil?
             return @tools if instance_variable_defined?(:@tools)
@@ -113,11 +73,6 @@ module Phronomy
             .reject { |_, value| value.nil? }
         end
 
-        # Returns the alias map registered via .tools.
-        # Merges parent class aliases so subclasses inherit their parent's mappings.
-        # Subclass-specific aliases take precedence over parent aliases.
-        # @return [Hash{Class => String}]
-        # @api public
         def tool_aliases
           own = @tool_aliases || {}
           if superclass.respond_to?(:tool_aliases)
@@ -127,18 +82,6 @@ module Phronomy
           end
         end
 
-        # Sets or reads the LLM provider for this agent.
-        # Required when using a model not registered in RubyLLM's model registry
-        # (e.g. locally-hosted models via LM Studio or Ollama).
-        #
-        # @param name [Symbol, nil] e.g. +:openai+, +:anthropic+, +:ollama+
-        # @return [Symbol, nil]
-        # @example
-        #   class MyAgent < Phronomy::Agent::Base
-        #     model "openai/gpt-oss-20b"
-        #     provider :openai
-        #   end
-        # @api public
         def provider(name = nil)
           if name
             @provider = name
@@ -148,16 +91,6 @@ module Phronomy
           end
         end
 
-        # Sets or reads the sampling temperature sent to the LLM.
-        # When nil, the provider's default is used.
-        #
-        # @param val [Float, nil] temperature (0.0 to 2.0 depending on provider)
-        # @return [Float, nil]
-        # @example
-        #   class MyAgent < Phronomy::Agent::Base
-        #     temperature 0.2
-        #   end
-        # @api public
         def temperature(val = nil)
           if val
             @temperature = val
@@ -166,16 +99,6 @@ module Phronomy
           end
         end
 
-        # Sets or reads the maximum number of LLM call cycles for ReAct agents.
-        # Each tool call and follow-up counts as one iteration. Defaults to 10.
-        #
-        # @param val [Integer, nil]
-        # @return [Integer]
-        # @example
-        #   class MyAgent < Phronomy::Agent::Base
-        #     max_iterations 5
-        #   end
-        # @api public
         def max_iterations(val = nil)
           if val
             @max_iterations = val
@@ -184,10 +107,6 @@ module Phronomy
           end
         end
 
-        # When enabled, attaches Anthropic prompt-cache markers to the system
-        # message so that the fixed instructions are served from cache on
-        # subsequent turns, reducing input-token costs.
-        # @api public
         def cache_instructions(enabled = nil)
           if enabled.nil?
             @cache_instructions
@@ -196,9 +115,6 @@ module Phronomy
           end
         end
 
-        # Tokens to reserve for the model's output.
-        # When nil, the model's max_output_tokens from the registry is used.
-        # @api public
         def max_output_tokens(val = nil)
           if val.nil?
             @max_output_tokens
@@ -207,8 +123,6 @@ module Phronomy
           end
         end
 
-        # Overrides the context window size used for token budget calculations.
-        # @api public
         def context_window(val = nil)
           if val.nil?
             @context_window
@@ -217,105 +131,216 @@ module Phronomy
           end
         end
 
-        # Defines or reads the stable Agent definition identity.
-        # Subclass with no explicit declaration inherits the parent's definition.
-        def agent_definition(id: nil, version: nil)
-          if id || version
-            raise ArgumentError, "agent_definition requires id: and version:" unless id && version
-            @agent_definition = {id: id.to_s.freeze, version: Integer(version)}.freeze
+        # Binds one Application-constructed ContextPolicy instance to this
+        # Agent class. Policy binding is Application code/runtime wiring rather
+        # than durable Agent state.
+        def context_policy(*args)
+          if args.empty?
+            return @context_policy if instance_variable_defined?(:@context_policy)
+            return superclass.context_policy if superclass.respond_to?(:context_policy)
+            return ContextPolicies::Default.instance
           end
-          return @agent_definition if @agent_definition
+          unless args.length == 1 && args.first.is_a?(ContextPolicy)
+            raise ArgumentError,
+              "context_policy expects one Phronomy::Agent::ContextPolicy instance"
+          end
+
+          @context_policy = args.first
+        end
+
+        def agent_definition(id: nil, version: nil)
+          if !id.nil? || !version.nil?
+            raise ArgumentError, "agent_definition requires version:" if version.nil?
+
+            definition_id = id || name
+            unless definition_id
+              raise Phronomy::ConfigurationError,
+                "anonymous Agent class must declare agent_definition id: ..., version: ..."
+            end
 
-          klass = superclass
-          while klass.respond_to?(:agent_definition, true) &&
-              klass < Phronomy::Agent::Base
-            defn = klass.instance_variable_get(:@agent_definition)
-            return defn if defn
-            klass = klass.superclass
+            @agent_definition = {
+              id: definition_id.to_s.freeze,
+              version: Integer(version)
+            }.freeze
           end
+          return @agent_definition if @agent_definition
 
           raise Phronomy::ConfigurationError,
-            "#{name || self} must declare agent_definition id: ..., version: ..."
+            "#{name || self} must declare agent_definition version: ..."
         end
 
-        def create(agent_id: SecureRandom.uuid, context: nil, knowledge: [], persistence: nil, metadata: {})
+        def create(
+          agent_id: SecureRandom.uuid,
+          context: nil,
+          knowledge: [],
+          persistence: nil,
+          metadata: {},
+          on_event: nil,
+          &event_block
+        )
           new(
             agent_id: agent_id,
             context: context,
             knowledge: knowledge,
             persistence: persistence,
-            metadata: metadata
+            metadata: metadata,
+            on_event: on_event,
+            &event_block
           )
         end
 
-        def load(agent_id, persistence:)
-          new(agent_id: agent_id, persistence: persistence, load_existing: true)
+        # Resolves one existing logical Agent. A live process-local owner wins
+        # without a Persistence reload; otherwise the durable Agent is hydrated.
+        def load(agent_id, persistence:, on_event: nil, &event_block)
+          raise ArgumentError, "persistence is required" unless persistence
+          if on_event && event_block
+            raise ArgumentError, "Provide either on_event: or a block, not both"
+          end
+
+          key = agent_id.to_s
+          raise ArgumentError, "agent_id must not be empty" if key.empty?
+
+          listener_supplied = !on_event.nil? || !event_block.nil?
+          runtime = Phronomy::Runtime.instance
+          materialized = false
+
+          agent = runtime.__load_agent(key, expected_class: self) do |owner_runtime|
+            materialized = true
+            instance = __construct_owned_agent(
+              owner_runtime,
+              key,
+              agent_id: key,
+              persistence: persistence,
+              load_existing: true,
+              on_event: on_event,
+              &event_block
+            )
+            Phronomy::Agent::RecoveryCoordinator.new(instance).recover_on_load!
+            instance
+          end
+
+          unless agent.persistence.equal?(persistence)
+            raise Phronomy::ConfigurationError,
+              "Agent #{key.inspect} is already live with a different Persistence instance"
+          end
+
+          if !materialized && listener_supplied
+            raise Phronomy::ConfigurationError,
+              "Agent #{key.inspect} is already live; load cannot add, replace, or re-bind on_event"
+          end
+
+          agent
+        end
+
+        # Returns only the process-local live Agent owner. Does not access
+        # Persistence and returns nil when this Runtime has no live owner.
+        def get(agent_id)
+          Phronomy::Runtime.instance.__get_agent(agent_id, expected_class: self)
         end
 
         # Resolves the live Agent instance that currently owns execution_id in
-        # this process. This is a Runtime-local lookup, not durable rehydration.
+        # this process. The Runtime returns only a read-only ownership view;
+        # mutable Agent execution state remains EventLoop-owned.
         def live_for_execution(execution_id)
-          activation = Phronomy::Runtime.instance.__agent_activations.fetch(execution_id)
-          unless activation
+          owner = Phronomy::Runtime.instance.__agent_execution_owner(execution_id)
+          unless owner
             raise Phronomy::ExecutionRehydrationRequiredError,
-              "no live activation for #{execution_id}; durable rehydration is required"
+              "no live execution owner for #{execution_id}; durable rehydration is required"
           end
 
-          agent = activation.agent
+          agent = owner.agent
           unless agent.is_a?(self)
             raise ArgumentError,
-              "live activation #{execution_id} belongs to #{agent.class}, not #{self}"
+              "live execution #{execution_id} belongs to #{agent.class}, not #{self}"
           end
 
           agent
         end
+
+        private
+
+        def __construct_owned_agent(owner_runtime, reserved_agent_id, *args, **kwargs, &block)
+          instance = allocate
+          instance.send(:__prepare_runtime_owner!, owner_runtime, reserved_agent_id)
+          instance.send(:initialize, *args, **kwargs, &block)
+          instance
+        end
       end
 
       attr_reader :agent_id, :persistence
 
       def initialize(
-        agent_id: SecureRandom.uuid,
+        agent_id: nil,
         context: nil,
         knowledge: [],
         persistence: nil,
         metadata: {},
-        load_existing: false
+        load_existing: false,
+        on_event: nil,
+        &event_block
       )
-        @persistence = persistence ||
-          Phronomy.configuration.persistence ||
-          Phronomy::Persistence::InMemory.new
-        @agent_id = agent_id.to_s.freeze
+        if on_event && event_block
+          raise ArgumentError, "Provide either on_event: or a block, not both"
+        end
+        @_phronomy_event_listener = on_event || event_block
 
-        if load_existing
-          root = records = nil
-          @persistence.transaction do |tx|
-            root = tx.agents.load(@agent_id)
-            records = tx.journals.read(
-              @agent_id,
-              limit: root.journal_position
-            )
-          end
-          validate_loaded_definition!(root)
-          @root = root
-          @_phronomy_journal_records = Array(records).dup.freeze
+        reserved_agent_id = @_phronomy_reserved_agent_id
+        effective_agent_id = if agent_id.nil?
+          reserved_agent_id || SecureRandom.uuid.to_s
         else
-          @root = create_agent_root!(
+          agent_id.to_s
+        end
+        raise ArgumentError, "agent_id must not be empty" if effective_agent_id.empty?
+
+        if @_phronomy_runtime_owner_state == :constructing
+          unless reserved_agent_id == effective_agent_id
+            raise Phronomy::Error,
+              "Agent initializer changed reserved identity from " \
+              "#{reserved_agent_id.inspect} to #{effective_agent_id.inspect}"
+          end
+          initialize_owned_state(
+            agent_id: effective_agent_id,
             context: context,
             knowledge: knowledge,
-            metadata: metadata
+            persistence: persistence,
+            metadata: metadata,
+            load_existing: load_existing
           )
-          @_phronomy_journal_records = @persistence.journals.read(
-            @agent_id,
-            limit: @root.journal_position
-          ).dup.freeze
+          return
+        end
+
+        if load_existing
+          raise ArgumentError,
+            "load_existing: is an internal hydration option; use .load(agent_id, persistence:)"
+        end
+
+        runtime = Phronomy::Runtime.instance
+        begin
+          runtime.__create_agent(effective_agent_id, expected_class: self.class) do |owner_runtime|
+            __prepare_runtime_owner!(owner_runtime, effective_agent_id)
+            initialize_owned_state(
+              agent_id: effective_agent_id,
+              context: context,
+              knowledge: knowledge,
+              persistence: persistence,
+              metadata: metadata,
+              load_existing: false
+            )
+            self
+          end
+        rescue Phronomy::Persistence::ConflictError => error
+          raise Phronomy::AgentAlreadyExistsError,
+            "Agent #{effective_agent_id.inspect} already exists durably: #{error.message}"
         end
       end
 
       def agent_root
+        __assert_agent_accessible!
         @root
       end
 
       def journal_projection
+        __assert_agent_accessible!
         Agent::JournalProjection.new(
           agent_root: @root,
           records: _journal_records_snapshot
@@ -336,8 +361,6 @@ module Phronomy
         end
       end
 
-      # Logically clears all persistent Knowledge registered before this point.
-      # Raw Journal records remain append-only and are not deleted.
       def clear_knowledge!
         mutate_context!(:knowledge_cleared) do |root|
           root.with(
@@ -347,9 +370,8 @@ module Phronomy
         end
       end
 
-      # Appends persistent Knowledge to the Agent Journal. The live Agent owns the
-      # current logical root/Journal view; Persistence is advanced optimistically.
       def add_knowledge(content, metadata: {})
+        __assert_live_agent!
         current = agent_root
         next_root = nil
         appended = nil
@@ -402,41 +424,188 @@ module Phronomy
       end
 
       def purge!
-        persistence.transaction do |tx|
-          tx.executions.assert_idle!(agent_id)
-          tx.journals.delete(agent_id)
-          tx.executions.delete_for_agent(agent_id)
-          tx.agents.delete(agent_id)
+        return true if @_phronomy_runtime_owner_state == :purged
+
+        __assert_live_agent!
+        runtime = @_phronomy_runtime_owner
+        token = runtime.__begin_agent_purge(self)
+        if runtime.__agent_execution_admitted?(agent_id)
+          runtime.__abort_agent_purge(self, token)
+          raise Phronomy::AgentBusyError,
+            "Agent #{agent_id.inspect} has a nonterminal top-level execution"
+        end
+
+        begin
+          persistence.transaction do |tx|
+            tx.executions.assert_idle!(agent_id)
+            tx.journals.delete(agent_id)
+            tx.executions.delete_for_agent(agent_id)
+            tx.agents.delete(agent_id)
+          end
+        rescue Phronomy::AgentBusyError,
+          Phronomy::Persistence::ConflictError,
+          Phronomy::Persistence::NotFoundError,
+          Phronomy::Persistence::SerializationError,
+          ArgumentError
+          runtime.__abort_agent_purge(self, token)
+          raise
+        rescue
+          # Without F1 reconciliation support we cannot infer that a failed
+          # durable delete did not commit. Keep the identity fail-closed.
+          runtime.__leave_agent_purge_uncertain(self, token)
+          raise
+        end
+
+        runtime.__complete_agent_purge(self, token)
+        true
+      end
+
+      # Runtime ownership lifecycle hooks. These are internal coordination
+      # methods; application code must use new/create/load/get/purge!.
+      private
+
+      # @api private
+      def __prepare_runtime_owner!(runtime, reserved_agent_id)
+        @_phronomy_runtime_owner = runtime
+        @_phronomy_runtime_owner_state = :constructing
+        @_phronomy_reserved_agent_id = reserved_agent_id.to_s.freeze
+        self
+      end
+
+      # @api private
+      def __bind_runtime_owner!(runtime)
+        unless @_phronomy_runtime_owner.equal?(runtime) &&
+            @_phronomy_runtime_owner_state == :constructing
+          raise Phronomy::Error, "Agent Runtime ownership construction state is invalid"
+        end
+        @_phronomy_runtime_owner_state = :live
+        remove_instance_variable(:@_phronomy_reserved_agent_id) if
+          instance_variable_defined?(:@_phronomy_reserved_agent_id)
+        self
+      end
+
+      # @api private
+      def __mark_purging!(runtime)
+        unless @_phronomy_runtime_owner.equal?(runtime) &&
+            @_phronomy_runtime_owner_state == :live
+          raise Phronomy::Error, "Agent Runtime ownership purge state is invalid"
+        end
+        @_phronomy_runtime_owner_state = :purging
+        self
+      end
+
+      # @api private
+      def __restore_live_after_purge_abort!(runtime)
+        unless @_phronomy_runtime_owner.equal?(runtime) &&
+            @_phronomy_runtime_owner_state == :purging
+          raise Phronomy::Error, "Agent Runtime ownership purge rollback state is invalid"
+        end
+        @_phronomy_runtime_owner_state = :live
+        self
+      end
+
+      # @api private
+      def __mark_ownership_recovery_required!(runtime)
+        unless @_phronomy_runtime_owner.equal?(runtime) &&
+            %i[constructing purging].include?(@_phronomy_runtime_owner_state)
+          raise Phronomy::Error, "Agent Runtime ownership recovery state is invalid"
+        end
+        @_phronomy_runtime_owner_state = :recovery_required
+        self
+      end
+
+      # @api private
+      def __mark_purged!(runtime)
+        unless @_phronomy_runtime_owner.equal?(runtime) &&
+            @_phronomy_runtime_owner_state == :purging
+          raise Phronomy::Error, "Agent Runtime ownership purge completion state is invalid"
         end
         @root = nil
         @_phronomy_journal_records = [].freeze
-        true
+        @_phronomy_runtime_owner_state = :purged
+        self
       end
 
-      # Internal hook used after a successful Persistence transaction.
+      # @api private
+      def __release_runtime_owner!(runtime)
+        return self if @_phronomy_runtime_owner_state == :purged
+        return self unless @_phronomy_runtime_owner.equal?(runtime)
+
+        @_phronomy_runtime_owner_state = :released
+        self
+      end
+
+      public
+
+      # Internal EventLoop apply hook used only after a successful durable
+      # operation result has been validated by ExecutionCoordinator.
       def __replace_root(root)
         @root = root
       end
 
       private
 
+      attr_reader :_phronomy_event_listener
+
+      def initialize_owned_state(
+        agent_id:,
+        context:,
+        knowledge:,
+        persistence:,
+        metadata:,
+        load_existing:
+      )
+        @persistence = persistence ||
+          Phronomy.configuration.persistence ||
+          Phronomy::Persistence::InMemory.new
+        @agent_id = agent_id.to_s.freeze
+
+        if load_existing
+          root = records = nil
+          @persistence.transaction do |tx|
+            root = tx.agents.load(@agent_id)
+            records = tx.journals.read(
+              @agent_id,
+              limit: root.journal_position
+            )
+          end
+          validate_loaded_definition!(root)
+          @root = root
+          @_phronomy_journal_records = Array(records).dup.freeze
+        else
+          @root = create_agent_root!(
+            context: context,
+            knowledge: knowledge,
+            metadata: metadata
+          )
+          @_phronomy_journal_records = @persistence.journals.read(
+            @agent_id,
+            limit: @root.journal_position
+          ).dup.freeze
+        end
+      end
+
       def validate_loaded_definition!(loaded)
         definition = self.class.agent_definition
-        return if loaded.agent_definition_id == definition.fetch(:id) &&
-          loaded.definition_version == definition.fetch(:version)
+        return if current_definition_compatible?(loaded, definition)
 
         raise Phronomy::ConfigurationError,
           "Agent definition mismatch for #{@agent_id}: stored " \
-          "#{loaded.agent_definition_id}@#{loaded.definition_version}, runtime " \
+          "#{loaded.agent_definition_id}@#{loaded.agent_definition_version}, runtime " \
           "#{definition.fetch(:id)}@#{definition.fetch(:version)}"
       end
 
+      def current_definition_compatible?(loaded, runtime_definition)
+        loaded.agent_definition_id == runtime_definition.fetch(:id) &&
+          loaded.agent_definition_version == runtime_definition.fetch(:version)
+      end
+
       def create_agent_root!(context:, knowledge:, metadata:)
         definition = self.class.agent_definition
         root = Agent::AgentRoot.create(
           agent_id: agent_id,
           agent_definition_id: definition.fetch(:id),
-          definition_version: definition.fetch(:version),
+          agent_definition_version: definition.fetch(:version),
           metadata: metadata
         )
         persistence.transaction do |tx|
@@ -507,6 +676,7 @@ module Phronomy
       end
 
       def mutate_context!(kind, context_affecting: true)
+        __assert_live_agent!
         current = agent_root
         next_root = nil
         appended = nil
@@ -541,7 +711,8 @@ module Phronomy
       end
 
       def yield_context_revision(current, proposed)
-        (proposed.context_revision == current.context_revision) ? current.context_revision + 1 : proposed.context_revision
+        (proposed.context_revision == current.context_revision) ?
+          current.context_revision + 1 : proposed.context_revision
       end
 
       def _journal_records_snapshot
@@ -558,44 +729,73 @@ module Phronomy
 
       public
 
-      def _add_handoff_tool(tool_class)
-        @_handoff_tools ||= []
-        @_handoff_tools << tool_class
-        self
-      end
-
-      def _handoff_tools
-        @_handoff_tools || []
-      end
-
       def tool_approval_policy(&block)
+        __assert_live_agent!
         raise ArgumentError, "tool_approval_policy requires a block" unless block
 
         _approval_configuration_mutex.synchronize { @tool_approval_policy = block }
         self
       end
 
-      def on_tool_approval_required(&block)
-        raise ArgumentError, "on_tool_approval_required requires a block" unless block
+      private
 
-        _approval_configuration_mutex.synchronize { @tool_approval_listener = block }
-        self
+      def __assert_agent_accessible!
+        case @_phronomy_runtime_owner_state
+        when :constructing, :live
+          true
+        when :purged
+          raise Phronomy::AgentPurgedError, "Agent #{agent_id.inspect} has been purged"
+        when :purging
+          raise Phronomy::Error, "Agent #{agent_id.inspect} is being purged"
+        when :recovery_required
+          raise Phronomy::Error,
+            "Agent #{agent_id.inspect} ownership requires durable recovery/reconciliation"
+        else
+          raise Phronomy::RuntimeShutdownError,
+            "Agent #{agent_id.inspect} is detached from its Runtime"
+        end
       end
 
-      private
+      def __assert_live_agent!
+        __assert_agent_accessible!
+        return true if @_phronomy_runtime_owner_state == :constructing
 
-      def _apply_invocation_context(thread_id, config, ic)
-        effective_thread_id = thread_id || ic.thread_id
-        effective_config = config.merge(invocation_context: ic)
-        if effective_config[:cancellation_token].nil?
-          if (tok = ic.effective_timeout_token)
+        runtime = @_phronomy_runtime_owner
+        unless runtime&.__agent_owned?(self)
+          raise Phronomy::RuntimeShutdownError,
+            "Agent #{agent_id.inspect} is no longer the live owner in its Runtime"
+        end
+        true
+      end
+
+      def _prepare_invocation_config(config, invocation_context)
+        __assert_live_agent!
+        _reject_removed_generic_identity_keys!(config)
+        effective_config = invocation_context ?
+          config.merge(invocation_context: invocation_context) : config
+
+        if invocation_context && effective_config[:cancellation_token].nil?
+          if (tok = invocation_context.effective_timeout_token)
             effective_config = effective_config.merge(
               cancellation_token: tok,
-              phronomy_timeout_deadline: ic.deadline
+              phronomy_timeout_deadline: invocation_context.deadline
             )
           end
         end
-        [effective_thread_id, effective_config]
+        effective_config
+      end
+
+      def _reject_removed_generic_identity_keys!(config)
+        removed_key = [
+          :thread_id, "thread_id",
+          :session_id, "session_id",
+          :agent_invocation_id, "agent_invocation_id"
+        ].find { |key| config.key?(key) }
+        return unless removed_key
+
+        raise ArgumentError,
+          "Agent identity #{removed_key.inspect} was removed; " \
+          "use purpose-specific domain identifiers or application tracing metadata"
       end
 
       def _check_event_loop_reentrancy(sync_method, async_method)
@@ -644,12 +844,12 @@ module Phronomy
         end
       end
 
-      def _report_stream_callback_error(callback_error, event:, invocation_id:,
+      def _report_stream_callback_error(callback_error, event:, execution_id:,
         callback_error_policy:)
         lines = [
           "[Phronomy] Stream callback failed",
           "event=#{event.type.inspect}",
-          "agent_invocation_id=#{invocation_id || "unknown"}",
+          "execution_id=#{execution_id || "unknown"}",
           "policy=#{callback_error_policy.inspect}",
           "error=#{callback_error.class}: #{callback_error.message}"
         ]
@@ -704,7 +904,6 @@ module Phronomy
       def _build_caller_meta(config)
         meta = {}
         meta[:user_id] = config[:user_id] if config[:user_id]
-        meta[:session_id] = config[:session_id] if config[:session_id]
         if (ic = config[:invocation_context])
           meta[:task_id] = ic.task_id if ic.task_id
           meta[:parent_task_id] = ic.parent_task_id if ic.parent_task_id
@@ -825,17 +1024,23 @@ module Phronomy
             }
           end
 
-          # Base#call_async ultimately executes #call, so the synchronous wrapper
-          # above already applies filters for ordinary Tools. Agent-backed Tools
-          # override #call_async and bypass #call; only those custom async Tools
-          # need an asynchronous result-filter wrapper here.
           if custom_async_call
             define_method(:call_async) do |args, **kwargs|
               source = super(args, **kwargs)
-              filtered = Phronomy::Task.deferred(name: "tool-filter-#{name}")
+              filtered = Phronomy::Concurrency::PhysicalCompletionTask.deferred(
+                name: "tool-filter-#{name}"
+              )
+              source_has_physical_signal = source.respond_to?(:on_physical_complete)
+              source.on_physical_complete { filtered.mark_physical_complete! } if
+                source_has_physical_signal
               source.on_complete do |value, error|
                 if error
-                  filtered.fail(error)
+                  filtered.mark_physical_complete! unless source_has_physical_signal
+                  if source.respond_to?(:status) && source.status == :cancelled
+                    filtered.cancel!(error)
+                  else
+                    filtered.fail(error)
+                  end
                   next
                 end
 
@@ -843,8 +1048,10 @@ module Phronomy
                   result = result_filters.inject(value) { |val, filter|
                     filter.call(val, tool_name: name, args: args)
                   }
+                  filtered.mark_physical_complete! unless source_has_physical_signal
                   filtered.complete(result)
                 rescue => filter_error
+                  filtered.mark_physical_complete! unless source_has_physical_signal
                   filtered.fail(filter_error)
                 end
               end