phronomy 0.29.0 → 0.30.1

data/lib/phronomy/agent/execution_observation.rb

@@ -5,14 +5,14 @@ module Phronomy
     # Stable domain observation; does not expose repositories or FSM phases.
     # @api public
     ExecutionObservation = Data.define(:agent_id, :execution_id, :status, :result,
-      :error, :reservation, :transfer_receipt, :cancellation_requested) do
-      def initialize(**values)
-        super(**values.transform_values { |value| Phronomy::Values::Immutable.copy(value) })
+      :error, :reservation, :transfer_receipt, :cancellation_requested, :raw_output) do
+      def initialize(raw_output: nil, **values)
+        super(raw_output: Phronomy::Values::Immutable.copy(raw_output), **values.transform_values { |value| Phronomy::Values::Immutable.copy(value) })
       end
 
       def self.from_result(value)
         new(agent_id: value.fetch(:agent_id), execution_id: value.fetch(:execution_id), status: value.fetch(:status),
-          result: value[:result], error: value[:error], reservation: nil, transfer_receipt: nil, cancellation_requested: false)
+          result: value[:result], raw_output: value[:raw_output], error: value[:error], reservation: nil, transfer_receipt: nil, cancellation_requested: false)
       end
 
       def absent? = status == :absent
@@ -28,7 +28,7 @@ module Phronomy
 
       def to_result
         Phronomy::Values::Immutable.copy(execution_id: execution_id, agent_id: agent_id,
-          status: status, result: result, output: result, error: error)
+          status: status, result: result, output: result, raw_output: raw_output, error: error)
       end
     end
   end

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

@@ -15,24 +15,20 @@ module Phronomy
 
         scope = new(environment: ExecutionEnvironment.current)
         result = nil
+        primary = nil
         begin
-          result = yield(scope)
-          result = result.wait_result if result.is_a?(Phronomy::TaskResult)
-        rescue Exception => primary # standard:disable Lint/RescueException
+          returned = yield(scope)
+          result = returned.is_a?(Phronomy::TaskResult) ? returned.wait_result : returned
+        rescue Exception => error # standard:disable Lint/RescueException
+          primary = error
           raise
         ensure
-          failures = scope.send(:__close)
-          if primary
-            failures.each do |failure|
-              error = failure.fetch(:error)
-              Phronomy::RuntimeSettings.current.logger&.warn(
-                "[Agent scope] cleanup failed agent_id=#{failure.fetch(:agent_id).inspect}: #{error.class}: #{error.message}"
-              )
-            rescue
-              nil
-            end
-          elsif failures.any?
-            raise ScopeCleanupError.new(failures: failures, result: result)
+          begin
+            scope.release!
+          rescue => cleanup
+            failures = cleanup.is_a?(ScopeCleanupError) ? cleanup.failures : [{agent_id: nil, error: cleanup}]
+            raise ScopeCleanupError.new(scope: scope, failures: failures, result: result,
+              primary_error: primary), cause: primary || failures.first.fetch(:error)
           end
         end
         result
@@ -83,27 +79,41 @@ module Phronomy
         Phronomy::TaskResult.failed(error)
       end
 
-      # @api private
-      def __close
+      # Release only safe owners; retain failed owners so the caller can retry.
+      # @api public
+      def release!
+        owns_release = false
+        check_blocking!
         agents = @mutex.synchronize do
-          @state = :closing
+          return false if @state == :released
+          raise Phronomy::Error.new("Agent scope is releasing", code: "agent.scope_busy") if @state == :releasing
+          @state = :releasing
+          owns_release = true
           @condition.wait(@mutex) until @receipts.empty?
           @agents.values.dup
         end
         failures = []
         agents.each do |agent|
           agent.unload!
+          @mutex.synchronize { @agents.delete(agent.object_id) }
         rescue => error
           failures << {agent_id: agent.agent_id, error: error}.freeze
         end
         @mutex.synchronize do
-          @agents.clear
-          @environment = @ownership = @owner_token = nil
-          @state = :closed
+          @state = failures.empty? ? :released : :release_failed
+          @environment = @ownership = @owner_token = nil if failures.empty?
+        end
+        unless failures.empty?
+          raise ScopeCleanupError.new(scope: self, failures: failures), cause: failures.first.fetch(:error)
+        end
+        true
+      ensure
+        # An interrupted waiter/unloader must remain retryable, without changing
+        # another thread's release state when this call was rejected as busy.
+        if owns_release
+          @mutex.synchronize { @state = :release_failed if @state == :releasing }
         end
-        failures.freeze
       end
-      private :__close
 
       private
 

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

@@ -6,11 +6,13 @@ module Phronomy
     # Original exceptions and the successful result remain available to the caller.
     # @api public
     class ScopeCleanupError < Phronomy::Error
-      attr_reader :failures, :result
+      attr_reader :failures, :result, :primary_error, :scope
 
-      def initialize(failures:, result:)
+      def initialize(scope:, failures:, result: nil, primary_error: nil)
         @failures = failures.map { |failure| failure.dup.freeze }.freeze
         @result = result
+        @primary_error = primary_error
+        @scope = scope
         super("Agent scope cleanup failed for: #{@failures.map { |f| f.fetch(:agent_id) }.join(", ")}",
           code: "agent.scope_cleanup_failed")
       end

data/lib/phronomy/agent/output_contract.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Phronomy
+  module Agent
+    # Owns the execution's output promise; generic schema interpretation is injected.
+    # @api private
+    class OutputContract
+      FACTORIES = {}
+      private_constant :FACTORIES
+      attr_reader :schema, :digest
+
+      def self.install_factory(factory)
+        FACTORIES.replace(parser: factory).freeze
+      end
+
+      def initialize(schema)
+        @parser = FACTORIES.fetch(:parser).call(schema)
+        @schema = @parser.json_schema
+        @digest = Digest::SHA256.hexdigest(JSON.generate(@schema, sort_keys: true)).freeze
+        freeze
+      end
+
+      def metadata(contents)
+        {"output_contract" => {"version" => 1, "schema_ref" => contents.put_text(JSON.generate(schema, sort_keys: true)), "schema_digest" => digest}}
+      end
+
+      def self.restore(execution, contents)
+        stored = execution.metadata["output_contract"]
+        return nil unless stored
+        raise ArgumentError, "unsupported Agent output contract version" unless stored.fetch("version") == 1
+        contract = new(contents.fetch_json(stored.fetch("schema_ref")))
+        unless contract.digest == stored.fetch("schema_digest")
+          raise Phronomy::ContentStore::IntegrityError, "Agent output schema digest mismatch"
+        end
+        contract
+      end
+
+      def validate(output, response:, execution_id:)
+        raw = response&.content
+        reason = if response&.refusal || response&.finish_reason == :refusal
+          "model_refusal"
+        elsif !response || !%i[stop].include?(response.finish_reason) || !response.tool_calls.empty?
+          %i[length content_filter].include?(response&.finish_reason) ? response.finish_reason.to_s : "unknown_finish_reason"
+        elsif output.nil? || raw.nil?
+          "missing_output"
+        end
+        if reason
+          raise OutputError.new(execution_id: execution_id, schema_digest: digest, reason: reason, raw_output: raw)
+        end
+        @parser.parse(output)
+      rescue Phronomy::ParseError => error
+        reason = case error.code
+        when "output_parser.invalid_json" then "invalid_json"
+        when "output_parser.schema_mismatch" then "schema_mismatch"
+        else raise
+        end
+        raise OutputError.new(execution_id: execution_id, schema_digest: digest, reason: reason,
+          violations: error.details, raw_output: raw), cause: error
+      end
+    end
+  end
+end

data/lib/phronomy/agent/output_error.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    # A declared output contract could not be fulfilled. Tool effects remain facts.
+    # @api public
+    class OutputError < Phronomy::Error
+      CODES = {"invalid_json" => "agent.output_invalid", "schema_mismatch" => "agent.output_invalid",
+               "missing_output" => "agent.output_invalid", "model_refusal" => "agent.output_refused",
+               "length" => "agent.output_incomplete", "content_filter" => "agent.output_incomplete",
+               "unknown_finish_reason" => "agent.output_incomplete"}.freeze
+      private_constant :CODES
+
+      # @api public
+      attr_reader :execution_id, :schema_digest, :reason, :violations, :raw_output
+
+      # @api public
+      def initialize(execution_id:, schema_digest:, reason:, violations: [], raw_output: nil)
+        @execution_id = execution_id.to_s.dup.freeze
+        @schema_digest = schema_digest.to_s.dup.freeze
+        @reason = reason.to_s.dup.freeze
+        @violations = Phronomy::Values::Immutable.json(violations)
+        @raw_output = Phronomy::Values::Immutable.copy(raw_output)
+        super("Agent output contract failed: #{@reason}", code: CODES.fetch(@reason))
+      end
+
+      # Owner-defined facts for persistence and composition; no live exception values.
+      # @api private
+      def diagnostic(include_raw: true)
+        value = Phronomy::Error.diagnostic(self).merge("execution_id" => execution_id,
+          "schema_digest" => schema_digest, "reason" => reason, "violations" => violations)
+        value["raw_output"] = raw_output if include_raw
+        Phronomy::Values::Immutable.json(value)
+      end
+
+      # @api private
+      def self.restore(value)
+        error = new(execution_id: value.fetch("execution_id"), schema_digest: value.fetch("schema_digest"),
+          reason: value.fetch("reason"), violations: value.fetch("violations"), raw_output: value["raw_output"])
+        raise ArgumentError, "invalid Agent output diagnostic code" unless error.code == value.fetch("code")
+        if value["cause"]
+          begin
+            raise error, cause: Phronomy::Error.from_diagnostic(value.fetch("cause"))
+          rescue OutputError => restored
+            restored.set_backtrace(nil)
+            return restored
+          end
+        end
+        error
+      end
+    end
+  end
+end

data/lib/phronomy/agent/recovery/recovery_coordinator/continuation.rb

@@ -39,9 +39,9 @@ module Phronomy
           materializer = RuntimeInput.new(agent: agent, persistence: agent.persistence)
           messages = records.map { |record| materializer.materialize_journal_record(record) }.freeze
           assistant = messages.reverse.find { |message| message.role.to_sym == :assistant }
-          output, usage = SavedContextReader.provider_output_and_usage(agent, execution) if execution.phase.to_sym == :recovery_provider_completed
+          output, usage, response = SavedContextReader.provider_output_and_usage(agent, execution) if execution.phase.to_sym == :recovery_provider_completed
           RecoveryMaterial.new(projection: projection, messages: messages,
-            assistant_message: assistant, output: output, usage: usage,
+            assistant_message: assistant, output: output, usage: usage, response: response,
             cancellation_requested: agent.persistence.cancellation_requested?(agent_id: agent.agent_id, execution_id: execution.execution_id))
         end
 
@@ -73,7 +73,7 @@ module Phronomy
                 agent.send(:_phronomy_event_listener), messages: material.messages, cancellation_requested: material.cancellation_requested)
             end
             if execution.phase.to_sym == :recovery_provider_completed
-              invocation.output, invocation.usage = material.output, material.usage
+              invocation.apply_llm_response!(material.response)
             end
             prepare_saved_provider_calls(execution, invocation, material.assistant_message) if action == :framework_calls
           end

data/lib/phronomy/agent/recovery/recovery_coordinator/installation.rb

@@ -296,6 +296,7 @@ module Phronomy
           Phronomy::Tracing::Automatic.observe_task(
             task,
             "agent.execution",
+            usage: ->(value) { value.is_a?(Hash) ? value[:usage]&.to_h&.freeze : nil },
             agent_id: agent.agent_id,
             execution_id: execution.execution_id,
             mode: (

data/lib/phronomy/agent/recovery/recovery_coordinator.rb

@@ -39,7 +39,7 @@ module Phronomy
       )
       ResolutionResult = Data.define(:execution)
       ResolutionPreparation = Data.define(:execution, :material, :error)
-      RecoveryMaterial = Data.define(:projection, :messages, :assistant_message, :output, :usage, :cancellation_requested)
+      RecoveryMaterial = Data.define(:projection, :messages, :assistant_message, :output, :usage, :response, :cancellation_requested)
       RecoveryPlan = Data.define(
         :execution, :root, :manifest, :base_manifest,
         :projection, :classification, :material

data/lib/phronomy/agent/recovery/recovery_support.rb

@@ -30,7 +30,11 @@ module Phronomy
       end
 
       def error_from_failure(failure)
-        Phronomy::Error.from_diagnostic(failure)
+        if failure["class"] == "Phronomy::Agent::OutputError"
+          OutputError.restore(failure)
+        else
+          Phronomy::Error.from_diagnostic(failure)
+        end
       end
 
       def event_payload(execution, descriptor)

data/lib/phronomy/agent/runtime_binding/engine_session_builder.rb

@@ -23,7 +23,8 @@ module Phronomy
           declared_states: InvocationTransitions::DECLARED_STATES,
           wait_state_names: InvocationTransitions::WAIT_STATES,
           external_events: InvocationTransitions::EXTERNAL_EVENTS,
-          recursion_limit: InvocationTransitions.recursion_limit(invocation.agent.class.max_iterations),
+          recursion_limit: InvocationTransitions::AUTOMATIC_RECURSION_LIMIT,
+          recursion_limit_scope: :automatic_chain,
           event_loop: event_loop,
           resume_event: resume_event,
           resume_phase: resume_phase

data/lib/phronomy/agent/runtime_input.rb

@@ -5,8 +5,12 @@ module Phronomy
     class RuntimeInput
       RuntimeProjection = Data.define(
         :system, :messages, :tool_classes, :ask_message,
-        :model_config, :manifest, :manifest_ref
-      )
+        :model_config, :manifest, :manifest_ref, :response_schema
+      ) do
+        def initialize(response_schema: nil, **values)
+          super(**values, response_schema: response_schema)
+        end
+      end
 
       def initialize(agent:, persistence:, additional_tools: [])
         @agent = agent
@@ -45,7 +49,8 @@ module Phronomy
           ask_message: ask_message,
           model_config: Phronomy::Values::Immutable.copy(model_config),
           manifest: manifest,
-          manifest_ref: manifest_ref
+          manifest_ref: manifest_ref,
+          response_schema: manifest.response_schema_ref && Phronomy::Values::Immutable.json(fetch_json(manifest.response_schema_ref))
         )
       end
 
@@ -148,12 +153,18 @@ module Phronomy
         end
 
         tool_calls = materialize_tool_calls(payload["tool_calls"])
+        metadata = payload.fetch("metadata", {})
+        raise ArgumentError, "canonical message metadata must be a Hash" unless metadata.is_a?(Hash)
+        metadata = metadata.dup
+        # Preserve backend-owned values without interpreting them. Old records
+        # stored model_id only at the top level; retain that read compatibility.
+        metadata["model_id"] = payload["model_id"] if !metadata.key?("model_id") && payload["model_id"]
         Phronomy::LLMAdapter::Message.new(
           role: role,
           content: payload.fetch("content", nil),
           tool_calls: tool_calls,
           tool_call_id: payload["tool_call_id"],
-          metadata: {"model_id" => payload["model_id"]}.compact
+          metadata: metadata
         )
       end
 

data/lib/phronomy/agent/saved_context_reader.rb

@@ -48,7 +48,8 @@ module Phronomy
           cached: usage_hash["cached"] || usage_hash[:cached] || usage_hash["cache_read_tokens"] || usage_hash[:cache_read_tokens] || usage_hash["cached_tokens"] || usage_hash[:cached_tokens],
           cache_creation: usage_hash["cache_creation"] || usage_hash[:cache_creation] || usage_hash["cache_write_tokens"] || usage_hash[:cache_write_tokens] || usage_hash["cache_creation_tokens"] || usage_hash[:cache_creation_tokens]
         )
-        [output, usage]
+        response = Phronomy::LLMAdapter::Response.from_h(payload.merge("usage" => usage.to_h))
+        [output, usage, response]
       end
     end
   end

data/lib/phronomy/agent/store.rb

@@ -79,7 +79,8 @@ module Phronomy
           execution_id: execution.execution_id, agent_id: execution.agent_id,
           status: execution.status, phase: execution.phase,
           result_ref: execution.result_ref, error_ref: execution.error_ref,
-          result: execution.result_ref && contents.fetch_text(execution.result_ref),
+          result: materialize_result(execution, contents),
+          raw_output: execution.metadata["raw_output_ref"] && contents.fetch_text(execution.metadata.fetch("raw_output_ref")),
           error: execution.error_ref && contents.fetch_json(execution.error_ref)
         }.then { |value| Phronomy::Values::Immutable.copy(value) }
       end
@@ -97,7 +98,8 @@ module Phronomy
           assert_execution_owner!(execution, agent_id)
           ExecutionObservation.new(agent_id: execution.agent_id, execution_id: execution.execution_id,
             status: execution.status,
-            result: execution.result_ref && records.contents.fetch_text(execution.result_ref),
+            result: materialize_result(execution, records.contents),
+            raw_output: execution.metadata["raw_output_ref"] && records.contents.fetch_text(execution.metadata.fetch("raw_output_ref")),
             error: execution.error_ref && Phronomy::Values::Immutable.copy(records.contents.fetch_json(execution.error_ref)),
             reservation: execution.metadata["reservation"] && ReservedExecution.new(agent_id: agent_id,
               execution_id: execution_id, correlation: execution.metadata["reservation"]),
@@ -226,6 +228,12 @@ module Phronomy
 
       private
 
+      def materialize_result(execution, contents)
+        return nil unless execution.result_ref
+        (execution.metadata["result_format"] == "json") ?
+          Phronomy::Values::Immutable.json(contents.fetch_json(execution.result_ref)) : contents.fetch_text(execution.result_ref)
+      end
+
       def authorized_argument_values(entry)
         # Unit 6 persists the exact validated snapshot. Older records encoded
         # legacy raw params, whose explicit optional nil meant omission.

data/lib/phronomy/common/values/immutable.rb

@@ -11,6 +11,39 @@ module Phronomy
     module Immutable
       module_function
 
+      # Normalize JSON object names without coercing values or losing duplicates.
+      # @api private
+      def json(value, ancestors: [])
+        if (value.is_a?(Hash) || value.is_a?(Array)) && ancestors.include?(value.object_id)
+          raise ArgumentError, "cyclic JSON value"
+        end
+        children = ancestors + [value.object_id]
+        normalized = case value
+        when Hash
+          value.each_with_object({}) do |(key, child), result|
+            unless key.is_a?(String) || key.is_a?(Symbol)
+              raise ArgumentError, "JSON object keys must be Strings or Symbols"
+            end
+            name = key.to_s
+            raise ArgumentError, "duplicate JSON object key: #{name}" if result.key?(name)
+            result[name.dup.freeze] = json(child, ancestors: children)
+          end
+        when Array then value.map { |child| json(child, ancestors: children) }
+        when String
+          text = value.encode(Encoding::UTF_8)
+          raise ArgumentError, "invalid UTF-8 JSON string" unless text.valid_encoding?
+          text.dup
+        when Integer, TrueClass, FalseClass, NilClass then value
+        when Float
+          raise ArgumentError, "JSON numbers must be finite" unless value.finite?
+          value
+        else raise ArgumentError, "unsupported JSON value: #{value.class}"
+        end
+        normalized.freeze
+      rescue EncodingError
+        raise ArgumentError, "invalid UTF-8 JSON string"
+      end
+
       # @api private
       def copy(value)
         case value

data/lib/phronomy/context/assembly.rb

@@ -34,7 +34,7 @@ module Phronomy
         )
       end
 
-      def store(prepared, contents:)
+      def store(prepared, contents:, response_schema_ref: nil)
         unless prepared.is_a?(Prepared)
           raise ArgumentError, "Context::Assembly#store expected Context::Assembly::Prepared"
         end
@@ -80,7 +80,7 @@ module Phronomy
         ).validate!(
           token_budget: prepared.input.token_budget,
           segments: segments,
-          extra_values: [selected_tool_definitions]
+          extra_values: [selected_tool_definitions, response_schema_ref && contents.fetch_json(response_schema_ref)].compact
         )
 
         store_manifest(
@@ -90,7 +90,8 @@ module Phronomy
           segments: segments,
           model_config_ref: contents.put_json(prepared.model_config),
           tool_definitions_ref: contents.put_json(selected_tool_definitions),
-          adapter_identity: prepared.adapter_identity
+          adapter_identity: prepared.adapter_identity,
+          response_schema_ref: response_schema_ref
         )
       end
 
@@ -117,7 +118,8 @@ module Phronomy
         segments:,
         model_config_ref:,
         tool_definitions_ref:,
-        adapter_identity:
+        adapter_identity:,
+        response_schema_ref:
       )
         positioned = segments.each_with_index.map do |value, position|
           Phronomy::Context::LLMInputManifest::Segment.new(**value.merge(position: position))
@@ -128,6 +130,7 @@ module Phronomy
           segments: positioned,
           model_config_ref: model_config_ref,
           tool_definitions_ref: tool_definitions_ref,
+          response_schema_ref: response_schema_ref,
           assembly_policy_version: ASSEMBLY_POLICY_VERSION,
           ruby_llm_version: adapter_identity["sdk_version"],
           adapter_name: adapter_identity["adapter_name"]

data/lib/phronomy/embeddings/backends/ruby_llm_embeddings.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "faraday"
+
 module Phronomy
   module Embeddings
     # Embeddings adapter backed by RubyLLM.
@@ -44,7 +46,7 @@ module Phronomy
         raise AuthenticationError.new(error.message, code: "embeddings.authentication_failed"), cause: error
       rescue ::RubyLLM::RateLimitError => error
         raise RateLimitError.new(error.message, code: "embeddings.rate_limited"), cause: error
-      rescue ::RubyLLM::Error => error
+      rescue ::RubyLLM::Error, ::Faraday::TimeoutError, ::Faraday::ConnectionFailed => error
         raise TransportError.new(error.message), cause: error
       end
     end

data/lib/phronomy/engine/fsm_session.rb

@@ -93,6 +93,7 @@ module Phronomy
       phase_machine_class:,
       recursion_limit:,
       event_loop:,
+      recursion_limit_scope: :session,
       resume_event: nil,
       resume_phase: nil,
       stable_observer: nil,
@@ -123,6 +124,11 @@ module Phronomy
       @external_events = external_events
       @phase_machine_class = phase_machine_class
       @recursion_limit = recursion_limit
+      unless %i[session automatic_chain].include?(recursion_limit_scope)
+        raise ArgumentError, "unknown recursion_limit_scope: #{recursion_limit_scope.inspect}"
+      end
+      @recursion_limit_scope = recursion_limit_scope
+      @automatic_steps = 0
       @event_loop = event_loop
       @resume_event = resume_event
       @resume_phase = resume_phase
@@ -230,7 +236,13 @@ module Phronomy
     end
 
     def fire_and_advance!(event)
-      if @step >= @recursion_limit
+      automatic = event.type == :state_completed
+      exhausted = if @recursion_limit_scope == :automatic_chain
+        automatic && @automatic_steps >= @recursion_limit
+      else
+        @step >= @recursion_limit
+      end
+      if exhausted
         raise Phronomy::RecursionLimitError,
           "Recursion limit (#{@recursion_limit}) exceeded"
       end
@@ -246,6 +258,9 @@ module Phronomy
       apply_context_metadata!
       @current_state = @tracker.phase.to_sym
       @step += 1
+      # Only an accepted external transition starts a fresh automatic chain.
+      # Consumed/stale events and events with no transition cannot reset it.
+      @automatic_steps = automatic ? @automatic_steps + 1 : 0
       advance_or_halt
     ensure
       @tracker.current_event = nil if @tracker&.respond_to?(:current_event=)

data/lib/phronomy/generation/generator_verifier/agent_operation.rb

@@ -8,23 +8,27 @@ module Phronomy
     # still pending. Generation owns the request-to-Workflow correlation.
     # @api private
     class AgentOperation
-      def initialize(agent_class)
+      def initialize(agent_class, output_schema:)
+        @output_schema = output_schema
         @mutex = Mutex.new
         @pending = []
         @agent = agent_class.new(on_event: method(:receive_event))
       end
 
-      def start(input, listener:)
+      def start(input, listener:, config: {})
         request = Object.new
         # Workflow entry calls are serial. Keep submitted requests until their
         # own result settles: Agent admission itself may run after an earlier
         # request completes, so a pending submission is not necessarily busy.
         @mutex.synchronize { @pending << [request, listener] }
-        task = @agent.invoke_async(input)
+        task = @agent.invoke_async(input, config: config, output_schema: @output_schema)
         task.on_complete do |result, error|
           release(request)
-          # Handoff was not a generation completion in the event-based path.
-          next if !error && result.is_a?(Hash) && result[:handoff_request]
+          remember_execution(result[:execution_id]) if result.is_a?(Hash)
+          if !error && result.is_a?(Hash) && result[:handoff_request]
+            error = Phronomy::Error.new("GeneratorVerifier does not coordinate Handoff",
+              code: "generation.unsupported_handoff")
+          end
 
           event = if error
             type = if error.is_a?(Phronomy::TimeoutError)
@@ -46,10 +50,29 @@ module Phronomy
         raise
       end
 
+      def approve_async(request, approved:)
+        @agent.approve_async(request.execution_id, approval_request_id: request.id, approved: approved)
+      end
+
+      def cancel_async
+        execution_id = @mutex.synchronize { @execution_id }
+        @agent.cancel_async(execution_id) if execution_id
+      end
+
+      def unload!
+        @agent.unload!
+      end
+
       private
 
+      def remember_execution(execution_id)
+        @mutex.synchronize { @execution_id = execution_id } if execution_id
+      end
+
       def receive_event(event)
         return unless event.type == :approval_required
+        request = event.payload[:request]
+        remember_execution(request.execution_id) if request.respond_to?(:execution_id)
 
         listener = @mutex.synchronize { @pending.first&.last }
         listener&.call(event)