phronomy 0.29.0 → 0.30.0

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

@@ -5,11 +5,6 @@ module Phronomy
     # Converts Agent events to correlated Workflow events. PipelineState owns
     # stale-result rejection and all Workflow state mutation.
     class AgentResultReceiver
-      def initialize(draft_result_parser:, review_result_parser:)
-        @draft_result_parser = draft_result_parser
-        @review_result_parser = review_result_parser
-      end
-
       def draft_listener(workflow:, workflow_instance_id:, request_id:)
         agent_listener(:draft, workflow, workflow_instance_id, request_id) do |output|
           draft_payload(output)
@@ -25,20 +20,20 @@ module Phronomy
       private
 
       def draft_payload(output)
-        parsed = @draft_result_parser.call(output)
+        parsed = output
         {
-          draft: parsed[:answer].to_s,
-          self_score: clamp(parsed[:confidence]),
-          citations: normalize_citations(parsed[:citations])
+          draft: parsed.fetch("answer"),
+          self_score: parsed.fetch("confidence"),
+          citations: parsed.fetch("citations")
         }
       end
 
       def review_payload(output)
-        parsed = @review_result_parser.call(output)
+        parsed = output
         {
-          review_score: clamp(parsed[:score]),
-          approved: parsed[:approved] == true,
-          feedback: parsed[:feedback].to_s
+          review_score: parsed.fetch("score"),
+          approved: parsed.fetch("approved"),
+          feedback: parsed.fetch("feedback")
         }
       end
 
@@ -47,6 +42,11 @@ module Phronomy
           case agent_event.type
           when :done
             begin
+              if agent_event.payload[:rejected]
+                workflow.signal(workflow_instance_id: workflow_instance_id,
+                  event: :"#{phase}_rejected", payload: {request_id: request_id})
+                next
+              end
               payload = completion.call(agent_event.payload[:output])
               workflow.signal(
                 workflow_instance_id: workflow_instance_id,
@@ -60,9 +60,6 @@ module Phronomy
             error = agent_event.payload[:error] ||
               Phronomy::Error.new("#{phase.to_s.capitalize} Agent ended with #{agent_event.type}")
             signal_failure(workflow, workflow_instance_id, request_id, phase, error)
-          when :approval_required
-            error = Phronomy::Error.new("GeneratorVerifier #{phase} Agent suspended for approval")
-            signal_failure(workflow, workflow_instance_id, request_id, phase, error)
           end
         }
       end
@@ -70,20 +67,10 @@ module Phronomy
       def signal_failure(workflow, workflow_instance_id, request_id, phase, error)
         workflow.signal(
           workflow_instance_id: workflow_instance_id,
-          event: :"#{phase}_failed",
+          event: error.is_a?(Phronomy::Agent::OutputError) ? :"#{phase}_output_failed" : :"#{phase}_failed",
           payload: {request_id: request_id, error: error}
         )
       end
-
-      def clamp(value)
-        value.to_f.clamp(0.0, 1.0)
-      end
-
-      def normalize_citations(raw)
-        Array(raw).filter_map do |citation|
-          citation.is_a?(Hash) ? citation.transform_keys(&:to_sym) : nil
-        end
-      end
     end
   end
 end

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

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Phronomy
+  class GeneratorVerifier
+    # One application-visible Tool approval notification, scoped to an invocation.
+    # The C04 request carries display-safe details. Generation only routes replies.
+    class Approval
+      attr_reader :invocation_id, :phase, :request
+
+      def initialize(invocation:, operation:, phase:, request:)
+        @invocation, @operation = invocation, operation
+        @invocation_id, @phase, @request = invocation.id, phase, request
+        freeze
+      end
+
+      def respond_async(approved:)
+        unless approved == true || approved == false
+          return Phronomy::TaskResult.failed(ArgumentError.new("approved must be true or false"))
+        end
+        @invocation.respond(self) do
+          @operation.approve_async(@request, approved: approved)
+        end.map { nil }
+      end
+
+      def to_h
+        {invocation_id: @invocation_id, phase: @phase.to_s, request: @request.to_h}
+      end
+    end
+  end
+end

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

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Phronomy
+  class GeneratorVerifier
+    class CleanupError < Phronomy::Error
+      attr_reader :pipeline, :failures, :result, :primary_error
+
+      def initialize(pipeline:, failures:, result: nil, primary_error: nil, code: "generation.cleanup_failed")
+        @pipeline, @result, @primary_error = pipeline, result, primary_error
+        @failures = failures.map { |failure| failure.dup.freeze }.freeze
+        super("Could not release #{failures.length} GeneratorVerifier Agent(s)", code: code)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Phronomy
+  class GeneratorVerifier
+    # Owns one run's subscriptions, child observations and application approval route.
+    # Agent owns durable execution, authorization and physical release safety.
+    # @api private
+    class Invocation
+      attr_reader :id, :result, :config
+
+      def initialize(config:, on_approval:, on_finish:)
+        @id = SecureRandom.uuid.freeze
+        @result = Phronomy::TaskResult.deferred(name: "generation:#{@id}")
+        @mutex = Mutex.new
+        @pending = 0
+        @workflow_done = false
+        @finished = false
+        @approvals = []
+        @on_approval, @on_finish = on_approval, on_finish
+        @token = Phronomy::Concurrency::CancellationToken.new
+        @subscriptions = Phronomy::Concurrency::Subscriptions.new
+        @config = config.merge(cancellation_token: @token).freeze
+        @agent_config = {cancellation_token: @token}
+        @agent_config[:invocation_context] = config[:invocation_context] if config.key?(:invocation_context)
+        @agent_config.freeze
+        @subscriptions.cancellation(config[:cancellation_token]) { @token.cancel! }
+      end
+
+      def approvals
+        @mutex.synchronize { @approvals.dup.freeze }
+      end
+
+      def cancel
+        @token.cancel!
+      end
+
+      def start(operation, phase, input, listener:)
+        observe do
+          @token.raise_if_cancelled!
+          operation.start(input, config: @agent_config, listener: ->(event) {
+            if event.type == :approval_required
+              notify_approval(operation, phase, event.payload.fetch(:request))
+            else
+              listener.call(event)
+            end
+          })
+        end
+      end
+
+      def respond(approval)
+        observe(check_approval: approval) { yield }
+      rescue => error
+        Phronomy::TaskResult.failed(error)
+      end
+
+      def follow(workflow_task, &build_result)
+        workflow_task.on_complete do |state, error|
+          begin
+            value = build_result.call(state) unless error
+          rescue => result_error
+            error = result_error
+          end
+          finish_workflow(value, error)
+        end
+        @result
+      end
+
+      def fail_start(error)
+        finish_workflow(nil, error)
+        @result
+      end
+
+      private
+
+      def notify_approval(operation, phase, request)
+        approval = Approval.new(invocation: self, operation: operation, phase: phase, request: request)
+        deliver = @mutex.synchronize do
+          next false if @workflow_done || @finished
+          @approvals << approval
+          true
+        end
+        @on_approval&.call(approval) if deliver
+      rescue => error
+        @mutex.synchronize { @primary_error ||= error }
+        cancel
+      end
+
+      def observe(check_approval: nil)
+        reserved = false
+        observed = false
+        @mutex.synchronize do
+          if @finished || @workflow_done || (check_approval && !@approvals.include?(check_approval))
+            raise Phronomy::Error.new("Generation invocation is no longer accepting operations",
+              code: "generation.inactive")
+          end
+          @pending += 1
+          reserved = true
+        end
+        task = yield
+        unless task.is_a?(Phronomy::TaskResult)
+          raise TypeError, "Agent operation must return TaskResult"
+        end
+        task.on_complete { |_value, _error| child_finished }
+        observed = true
+        task
+      ensure
+        child_finished if reserved && !observed
+      end
+
+      def child_finished
+        @mutex.synchronize { @pending -= 1 }
+        try_finish
+      end
+
+      def finish_workflow(value, error)
+        @mutex.synchronize do
+          @workflow_done = true
+          @value, @error = value, error
+        end
+        cancel if error
+        try_finish
+      end
+
+      def try_finish
+        completion = @mutex.synchronize do
+          next if @finished || !@workflow_done || !@pending.zero?
+          @finished = true
+          [@value, @primary_error || @error]
+        end
+        return unless completion
+
+        @subscriptions.close
+        @on_finish.call
+        value, error = completion
+        if error.is_a?(Phronomy::CancellationError)
+          @result.cancel!(error)
+        elsif error
+          @result.fail(error)
+        else
+          @result.complete(value)
+        end
+      end
+    end
+  end
+end

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

@@ -16,6 +16,7 @@ module Phronomy
       field :output, type: :replace, default: -> { {} }
       field :draft_request_id, type: :replace, default: nil
       field :review_request_id, type: :replace, default: nil
+      field :interrupted_phase, type: :replace, default: nil
       field :pipeline_error, type: :replace, default: nil
 
       # Application-level event interpretation. Correlation IDs belong to this
@@ -39,6 +40,21 @@ module Phronomy
           self.review_notes = review_notes + [event.payload[:feedback]]
           self.review_request_id = nil
           self.pipeline_error = nil
+        when :draft_rejected
+          return :consume unless event.payload[:request_id] == draft_request_id
+          self.interrupted_phase = :draft
+          self.draft_request_id = nil
+        when :review_rejected
+          return :consume unless event.payload[:request_id] == review_request_id
+          self.interrupted_phase = :review
+          self.review_request_id = nil
+        when :draft_output_failed, :review_output_failed
+          phase = (event.type == :draft_output_failed) ? :draft : :review
+          expected = (phase == :draft) ? draft_request_id : review_request_id
+          return :consume unless event.payload[:request_id] == expected
+          self.pipeline_error = event.payload.fetch(:error)
+          self.interrupted_phase = phase
+          (phase == :draft) ? self.draft_request_id = nil : self.review_request_id = nil
         when :draft_failed
           return :consume unless event.payload[:request_id] == draft_request_id
 

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

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Phronomy
+  class GeneratorVerifier
+    # Generation defines the information it needs. Agent owns schema validation.
+    # @api private
+    module Protocol
+      DEFAULT_CITATION = Phronomy::Values::Immutable.json({
+        type: "object", properties: {source: {type: "string"}, excerpt: {type: "string"}},
+        required: %w[source excerpt], additionalProperties: false
+      })
+      REVIEW = Phronomy::Values::Immutable.json({
+        type: "object", properties: {approved: {type: "boolean"}, score: {type: "number", minimum: 0, maximum: 1},
+                                     feedback: {type: "string"}},
+        required: %w[approved score feedback], additionalProperties: false
+      })
+
+      module_function
+
+      def draft(citation_schema)
+        citation = Phronomy::Values::Immutable.json(citation_schema)
+        unless citation.is_a?(Hash) && citation["type"] == "object"
+          raise ArgumentError, "citation_schema must declare an object"
+        end
+        Phronomy::Values::Immutable.json({
+          type: "object", properties: {answer: {type: "string"}, confidence: {type: "number", minimum: 0, maximum: 1},
+                                       citations: {type: "array", items: embed_citation(citation)}},
+          required: %w[answer confidence citations], additionalProperties: false
+        })
+      end
+
+      # A local citation reference is relative to the citation document. Rebase
+      # only schema positions when embedding it, leaving const/enum data intact.
+      def embed_citation(node)
+        return node unless node.is_a?(Hash)
+        node.to_h do |key, value|
+          transformed = case key
+          when "$ref"
+            (value.is_a?(String) && value.start_with?("#")) ? "#/properties/citations/items#{value.delete_prefix("#")}" : value
+          when "properties", "$defs"
+            value.is_a?(Hash) ? value.transform_values { |child| embed_citation(child) } : value
+          when "items", "additionalProperties"
+            embed_citation(value)
+          when "anyOf"
+            value.is_a?(Array) ? value.map { |child| embed_citation(child) } : value
+          else
+            value
+          end
+          [key, transformed]
+        end
+      end
+      private_class_method :embed_citation
+    end
+  end
+end

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

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module Phronomy
+  class GeneratorVerifier
+    # Immutable, JSON-reconstructible facts about one generation attempt.
+    # Acceptance is the configured evaluation outcome, not application publication.
+    class Result
+      FIELDS = %i[output confidence citations iterations review_notes
+        confidence_threshold review_approved termination_reason interrupted_phase failure].freeze
+      attr_reader(*FIELDS)
+
+      def self.accepted?(confidence:, confidence_threshold:, review_approved:)
+        review_approved == true && !confidence.nil? && confidence >= confidence_threshold
+      end
+
+      def self.from_h(hash)
+        raise ArgumentError, "Result data must be a Hash" unless hash.is_a?(Hash)
+        fields = hash.each_with_object({}) do |(key, value), result|
+          unless key.is_a?(String) || key.is_a?(Symbol)
+            raise ArgumentError, "Result keys must be String or Symbol"
+          end
+          key = key.to_sym
+          raise ArgumentError, "duplicate Result field: #{key}" if result.key?(key)
+          result[key] = value
+        end
+        raise ArgumentError, "unknown Result fields" unless (fields.keys - FIELDS).empty?
+        raise ArgumentError, "missing Result fields" unless (FIELDS - fields.keys).empty?
+        new(**fields)
+      end
+
+      def initialize(output:, confidence:, citations:, iterations:, review_notes:,
+        confidence_threshold:, review_approved:, termination_reason:, interrupted_phase: nil, failure: nil)
+        @output = output&.dup&.freeze
+        @confidence = score(confidence, optional: true)
+        @confidence_threshold = score(confidence_threshold)
+        @review_approved = review_approved
+        @termination_reason = termination_reason.to_s.freeze
+        @interrupted_phase = interrupted_phase&.to_s&.freeze
+        @failure = Phronomy::Values::Immutable.json(failure)
+        @iterations = iterations
+        @citations = Phronomy::Values::Immutable.json(citations)
+        @review_notes = Phronomy::Values::Immutable.copy(review_notes)
+        validate!
+        freeze
+      end
+
+      def accepted?
+        @termination_reason == "accepted"
+      end
+
+      def to_h
+        FIELDS.to_h { |field| [field, public_send(field)] }
+      end
+
+      def ==(other)
+        other.instance_of?(self.class) && to_h == other.to_h
+      end
+      alias_method :eql?, :==
+
+      def hash
+        [self.class, to_h].hash
+      end
+
+      private
+
+      def score(value, optional: false)
+        return nil if optional && value.nil?
+        unless value.is_a?(Numeric) && value.real? && value.to_f.finite? && (0.0..1.0).cover?(value)
+          raise ArgumentError, "scores and threshold must be finite numbers in 0..1"
+        end
+        value.to_f
+      end
+
+      def validate!
+        unless @output.nil? || @output.is_a?(String)
+          raise ArgumentError, "output must be a String or nil"
+        end
+        unless @iterations.is_a?(Integer) && @iterations >= 0
+          raise ArgumentError, "iterations must be a nonnegative Integer"
+        end
+        unless @citations.is_a?(Array) && @citations.all?(Hash) &&
+            @review_notes.is_a?(Array) && @review_notes.all?(String)
+          raise ArgumentError, "citations must be hashes and review_notes must be strings"
+        end
+        if @termination_reason == "output_failed"
+          unless @failure.is_a?(Hash) && %w[agent.output_invalid agent.output_refused agent.output_incomplete].include?(@failure["code"]) &&
+              %w[reason execution_id schema_digest].all? { |key| @failure[key].is_a?(String) && !@failure[key].empty? } &&
+              @failure["violations"].is_a?(Array) && @failure["class"] == "Phronomy::Agent::OutputError"
+            raise ArgumentError, "output failure requires a complete Agent output diagnostic"
+          end
+          reasons = {"agent.output_invalid" => %w[invalid_json schema_mismatch missing_output],
+                     "agent.output_refused" => %w[model_refusal],
+                     "agent.output_incomplete" => %w[length content_filter unknown_finish_reason]}
+          unless reasons.fetch(@failure.fetch("code")).include?(@failure.fetch("reason"))
+            raise ArgumentError, "output failure reason contradicts its code"
+          end
+          if @interrupted_phase == "draft"
+            raise ArgumentError, "failed draft cannot carry an earlier answer" unless @output.nil? && @citations.empty?
+          elsif @interrupted_phase == "review"
+            raise ArgumentError, "failed review requires a valid draft" unless @output.is_a?(String) && @iterations.positive?
+          end
+        elsif @failure
+          raise ArgumentError, "only output_failed may carry failure"
+        end
+        if %w[tool_rejected output_failed].include?(@termination_reason)
+          unless %w[draft review].include?(@interrupted_phase) && @review_approved.nil? && @confidence.nil?
+            raise ArgumentError, "interruption must identify its phase and has no completed evaluation"
+          end
+          return
+        end
+        unless @iterations.positive? && @output.is_a?(String) && !@confidence.nil? &&
+            [true, false].include?(@review_approved) && @interrupted_phase.nil?
+          raise ArgumentError, "completed evaluation requires output, score and boolean review_approved"
+        end
+        expected = self.class.accepted?(confidence: @confidence,
+          confidence_threshold: @confidence_threshold, review_approved: @review_approved) ? "accepted" : "iteration_limit"
+        raise ArgumentError, "termination_reason contradicts evaluation" unless @termination_reason == expected
+      end
+    end
+  end
+end

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

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Phronomy
+  class GeneratorVerifier
+    class UnacceptedResultError < Phronomy::Error
+      attr_reader :result
+
+      def initialize(result, code: "generation.result_unaccepted")
+        @result = result
+        super("Generation did not satisfy its evaluation conditions (#{result.termination_reason})", code: code)
+      end
+    end
+  end
+end

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

@@ -9,19 +9,16 @@ module Phronomy
       def initialize(
         draft_agent:, review_agent:,
         draft_prompt_builder:, review_prompt_builder:,
-        draft_result_parser:, review_result_parser:,
-        threshold:, max_iterations:
+        threshold:, max_iterations:, start_operation:
       )
+        @start_operation = start_operation
         @draft_agent = draft_agent
         @review_agent = review_agent
         @draft_prompt_builder = draft_prompt_builder
         @review_prompt_builder = review_prompt_builder
         @threshold = threshold
         @max_iterations = max_iterations
-        @result_receiver = AgentResultReceiver.new(
-          draft_result_parser: draft_result_parser,
-          review_result_parser: review_result_parser
-        )
+        @result_receiver = AgentResultReceiver.new
       end
 
       def build
@@ -48,6 +45,10 @@ module Phronomy
 
           transition from: :draft, on: :draft_completed, to: :review
           transition from: :draft, on: :draft_failed, to: :failed
+          transition from: :draft, on: :draft_output_failed, to: :finalize
+          transition from: :review, on: :review_output_failed, to: :finalize
+          transition from: :draft, on: :draft_rejected, to: :finalize
+          transition from: :review, on: :review_rejected, to: :finalize
           transition from: :review,
             on: :review_completed,
             guard: ready_to_finalize,
@@ -71,7 +72,7 @@ module Phronomy
           workflow_instance_id: next_state.workflow_instance_id,
           request_id: request_id
         )
-        @draft_agent.start(prompt, listener: listener)
+        @start_operation.call(@draft_agent, :draft, prompt, listener: listener)
         next_state
       end
 
@@ -86,18 +87,19 @@ module Phronomy
           workflow_instance_id: next_state.workflow_instance_id,
           request_id: request_id
         )
-        @review_agent.start(prompt, listener: listener)
+        @start_operation.call(@review_agent, :review, prompt, listener: listener)
         next_state
       end
 
       def ready_to_finalize?(state)
-        confidence = [state.self_score || 0.0, state.review_score || 0.0].min
-        (confidence >= @threshold && state.approved) ||
+        confidence = [state.self_score, state.review_score].min
+        Result.accepted?(confidence: confidence, confidence_threshold: @threshold, review_approved: state.approved) ||
           state.iteration >= @max_iterations
       end
 
       def finalize(state)
-        state.output = state.draft
+        state.output = (state.interrupted_phase == :draft) ? nil : state.draft
+        state.citations = [] if state.interrupted_phase == :draft
         state
       end