phronomy 0.26.0 → 0.27.0

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

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Phronomy
+  class GeneratorVerifier
+    # 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)
+        end
+      end
+
+      def review_listener(workflow:, workflow_instance_id:, request_id:)
+        agent_listener(:review, workflow, workflow_instance_id, request_id) do |output|
+          review_payload(output)
+        end
+      end
+
+      private
+
+      def draft_payload(output)
+        parsed = @draft_result_parser.call(output)
+        {
+          draft: parsed[:answer].to_s,
+          self_score: clamp(parsed[:confidence]),
+          citations: normalize_citations(parsed[:citations])
+        }
+      end
+
+      def review_payload(output)
+        parsed = @review_result_parser.call(output)
+        {
+          review_score: clamp(parsed[:score]),
+          approved: parsed[:approved] == true,
+          feedback: parsed[:feedback].to_s
+        }
+      end
+
+      def agent_listener(phase, workflow, workflow_instance_id, request_id, &completion)
+        ->(agent_event) {
+          case agent_event.type
+          when :done
+            begin
+              payload = completion.call(agent_event.payload[:output])
+              workflow.signal(
+                workflow_instance_id: workflow_instance_id,
+                event: :"#{phase}_completed",
+                payload: {request_id: request_id, **payload}
+              )
+            rescue => error
+              signal_failure(workflow, workflow_instance_id, request_id, phase, error)
+            end
+          when :error, :timeout, :cancelled
+            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
+
+      def signal_failure(workflow, workflow_instance_id, request_id, phase, error)
+        workflow.signal(
+          workflow_instance_id: workflow_instance_id,
+          event: :"#{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/pipeline_state.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Phronomy
+  class GeneratorVerifier
+    class PipelineState
+      include Phronomy::WorkflowContext
+
+      field :input, type: :replace, default: -> { "" }
+      field :draft, type: :replace, default: -> { {} }
+      field :self_score, type: :replace, default: -> { 0.0 }
+      field :review_score, type: :replace, default: -> { 0.0 }
+      field :citations, type: :replace, default: -> { [] }
+      field :review_notes, type: :append, default: -> { [] }
+      field :iteration, type: :replace, default: -> { 0 }
+      field :approved, type: :replace, default: -> { false }
+      field :output, type: :replace, default: -> { {} }
+      field :draft_request_id, type: :replace, default: nil
+      field :review_request_id, type: :replace, default: nil
+      field :pipeline_error, type: :replace, default: nil
+
+      # Application-level event interpretation. Correlation IDs belong to this
+      # Pipeline rather than to the generic FSMSession.
+      def handle_fsm_event(event)
+        case event.type
+        when :draft_completed
+          return :consume unless event.payload[:request_id] == draft_request_id
+
+          self.draft = event.payload[:draft]
+          self.self_score = event.payload[:self_score]
+          self.citations = event.payload[:citations]
+          self.iteration = iteration + 1
+          self.draft_request_id = nil
+          self.pipeline_error = nil
+        when :review_completed
+          return :consume unless event.payload[:request_id] == review_request_id
+
+          self.review_score = event.payload[:review_score]
+          self.approved = event.payload[:approved]
+          self.review_notes = review_notes + [event.payload[:feedback]]
+          self.review_request_id = nil
+          self.pipeline_error = nil
+        when :draft_failed
+          return :consume unless event.payload[:request_id] == draft_request_id
+
+          self.pipeline_error = event.payload[:error]
+          self.draft_request_id = nil
+        when :review_failed
+          return :consume unless event.payload[:request_id] == review_request_id
+
+          self.pipeline_error = event.payload[:error]
+          self.review_request_id = nil
+        end
+        false
+      end
+    end
+  end
+end

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

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Phronomy
+  class GeneratorVerifier
+    # Builds the generation/review loop; result reception does not mutate state.
+    class WorkflowBuilder
+      def initialize(
+        draft_agent:, review_agent:,
+        draft_prompt_builder:, review_prompt_builder:,
+        draft_result_parser:, review_result_parser:,
+        threshold:, max_iterations:
+      )
+        @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
+        )
+      end
+
+      def build
+        # The entry closures see the Workflow assigned after definition.
+        workflow = nil
+        draft_entry = ->(state) { start_draft(state, workflow) }
+        review_entry = ->(state) { start_review(state, workflow) }
+        finalize_entry = method(:finalize)
+        failed_entry = method(:fail_pipeline)
+        ready_to_finalize = method(:ready_to_finalize?)
+
+        workflow = Phronomy::Workflow.define(PipelineState) do
+          initial :draft
+
+          state :draft
+          state :review
+          state :finalize
+          state :failed
+
+          entry :draft, draft_entry
+          entry :review, review_entry
+          entry :finalize, finalize_entry
+          entry :failed, failed_entry
+
+          transition from: :draft, on: :draft_completed, to: :review
+          transition from: :draft, on: :draft_failed, to: :failed
+          transition from: :review,
+            on: :review_completed,
+            guard: ready_to_finalize,
+            to: :finalize
+          transition from: :review, on: :review_completed, to: :draft
+          transition from: :review, on: :review_failed, to: :failed
+
+          transition from: :finalize, to: :__finish__
+        end
+      end
+
+      private
+
+      def start_draft(state, workflow)
+        request_id = SecureRandom.uuid
+        next_state = state.merge(draft_request_id: request_id)
+        feedback = next_state.review_notes.last
+        prompt = @draft_prompt_builder.call(next_state.input, feedback)
+        listener = @result_receiver.draft_listener(
+          workflow: workflow,
+          workflow_instance_id: next_state.workflow_instance_id,
+          request_id: request_id
+        )
+        @draft_agent.send(:__invoke_async_with_event_sink, prompt, on_event: listener)
+        next_state
+      end
+
+      def start_review(state, workflow)
+        request_id = SecureRandom.uuid
+        next_state = state.merge(review_request_id: request_id)
+        prompt = @review_prompt_builder.call(
+          next_state.input, next_state.draft, next_state.citations
+        )
+        listener = @result_receiver.review_listener(
+          workflow: workflow,
+          workflow_instance_id: next_state.workflow_instance_id,
+          request_id: request_id
+        )
+        @review_agent.send(:__invoke_async_with_event_sink, prompt, on_event: 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) ||
+          state.iteration >= @max_iterations
+      end
+
+      def finalize(state)
+        state.output = state.draft
+        state
+      end
+
+      def fail_pipeline(state)
+        raise(
+          state.pipeline_error ||
+          Phronomy::Error.new("GeneratorVerifier Agent operation failed")
+        )
+      end
+    end
+  end
+end

data/lib/phronomy/generation/generator_verifier.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module Phronomy
+  # Implements the Generator-Verifier multi-agent coordination pattern.
+  #
+  # Agent completion is integrated through application-defined Workflow events;
+  # Workflow entry actions do not return or await Agent Tasks.
+  class GeneratorVerifier
+    DEFAULT_CONFIDENCE_THRESHOLD = 0.7
+    DEFAULT_MAX_ITERATIONS = 3
+
+    Result = Struct.new(
+      :output,
+      :confidence,
+      :citations,
+      :iterations,
+      :review_notes,
+      :trusted
+    ) do
+      alias_method :trusted?, :trusted
+    end
+
+    private_constant :PipelineState, :WorkflowBuilder, :AgentResultReceiver
+
+    def initialize(
+      draft_agent:,
+      review_agent:,
+      draft_prompt_builder:,
+      review_prompt_builder:,
+      draft_result_parser: nil,
+      review_result_parser: nil,
+      confidence_threshold: DEFAULT_CONFIDENCE_THRESHOLD,
+      max_iterations: DEFAULT_MAX_ITERATIONS,
+      raise_if_untrusted: false
+    )
+      @draft_agent_class = draft_agent
+      @review_agent_class = review_agent
+      @draft_prompt_builder = draft_prompt_builder
+      @review_prompt_builder = review_prompt_builder
+      @draft_result_parser =
+        draft_result_parser || method(:default_parse_draft)
+      @review_result_parser =
+        review_result_parser || method(:default_parse_review)
+      @threshold = confidence_threshold.to_f
+      @max_iterations = max_iterations.to_i
+      @raise_if_untrusted = raise_if_untrusted
+      @compiled_workflow = nil
+    end
+
+    def invoke(input, config: {})
+      state = compiled_workflow.invoke({input: input}, config: config)
+      confidence = combined_confidence(state)
+      trusted = confidence >= @threshold
+      result = Result.new(
+        output: state.output || state.draft.to_s,
+        confidence: confidence,
+        citations: state.citations,
+        iterations: state.iteration,
+        review_notes: state.review_notes,
+        trusted: trusted
+      )
+      if @raise_if_untrusted && !trusted
+        raise LowConfidenceError.new(result)
+      end
+      result
+    end
+
+    private
+
+    def combined_confidence(state)
+      [
+        (state.self_score || 0.0).to_f,
+        (state.review_score || 0.0).to_f
+      ].min
+    end
+
+    def compiled_workflow
+      @compiled_workflow ||= build_workflow
+    end
+
+    def build_workflow
+      WorkflowBuilder.new(
+        draft_agent: @draft_agent_class.new,
+        review_agent: @review_agent_class.new,
+        draft_prompt_builder: @draft_prompt_builder,
+        review_prompt_builder: @review_prompt_builder,
+        draft_result_parser: @draft_result_parser,
+        review_result_parser: @review_result_parser,
+        threshold: @threshold,
+        max_iterations: @max_iterations
+      ).build
+    end
+
+    def default_parse_draft(text)
+      json_parser.parse(text)
+    rescue Phronomy::ParseError
+      {
+        answer: text.to_s,
+        confidence: 0.0,
+        citations: []
+      }
+    end
+
+    def default_parse_review(text)
+      json_parser.parse(text)
+    rescue Phronomy::ParseError
+      {
+        approved: false,
+        score: 0.0,
+        feedback: "Review output could not be parsed: #{text}"
+      }
+    end
+
+    def json_parser
+      @json_parser ||= Phronomy::OutputParser::JsonParser.new
+    end
+  end
+end

data/lib/phronomy/generation/low_confidence_error.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require_relative "../common/error"
+
+module Phronomy
+  class LowConfidenceError < Error
+    attr_reader :result
+
+    def initialize(result)
+      @result = result
+      super("Answer confidence #{result.confidence} is below the required threshold")
+    end
+  end
+end

data/lib/phronomy/llm_context_window/token_budget.rb

@@ -2,20 +2,19 @@
 
 module Phronomy
   module LlmContextWindow
-    # Immutable arithmetic value for one resolved model context budget.
-    # Model-registry lookup belongs to Agent::TokenBudgetResolver.
+    # Immutable input-budget arithmetic. RubyLLM owns model capabilities.
     class TokenBudget
-      attr_reader :context_window, :max_output_tokens
+      attr_reader :max_input_tokens
 
       # @api private
-      def initialize(context_window:, max_output_tokens:)
-        @context_window = Integer(context_window)
-        @max_output_tokens = Integer(max_output_tokens)
+      def initialize(max_input_tokens:)
+        @max_input_tokens = Integer(max_input_tokens)
+        raise ArgumentError, "max_input_tokens must be positive" unless @max_input_tokens.positive?
       end
 
       # @api private
       def effective_input_limit
-        [@context_window - @max_output_tokens, 0].max
+        @max_input_tokens
       end
 
       # @api private

data/lib/phronomy/llm_contract/authentication_error.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require_relative "transport_error"
+
+module Phronomy
+  class AuthenticationError < TransportError; end
+end

data/lib/phronomy/{context_budget_exceeded_error.rb → llm_contract/context_budget_exceeded_error.rb}

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "../common/error"
+
 module Phronomy
   # Raised when mandatory context content (system instructions, tool definitions,
   # current input) exhausts the model's context window, leaving no room for

data/lib/phronomy/llm_contract/context_length_error.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require_relative "../common/error"
+
+module Phronomy
+  class ContextLengthError < Error; end
+end

data/lib/phronomy/llm_contract/rate_limit_error.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require_relative "transport_error"
+
+module Phronomy
+  class RateLimitError < TransportError; end
+end

data/lib/phronomy/{token_usage.rb → llm_contract/token_usage.rb}

@@ -43,8 +43,8 @@ module Phronomy
       new(
         input: tokens.input || 0,
         output: tokens.output || 0,
-        cached: tokens.cached || 0,
-        cache_creation: tokens.cache_creation || 0
+        cached: tokens.cache_read || 0,
+        cache_creation: tokens.cache_write || 0
       )
     end
 

data/lib/phronomy/llm_contract/transport_error.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require_relative "../common/error"
+
+module Phronomy
+  class TransportError < Error; end
+end

data/lib/phronomy/multi_agent/admission_registry.rb

@@ -2,18 +2,32 @@
 
 module Phronomy
   module MultiAgent
-    # Runtime-local admission for one user-facing coordination turn per main Agent.
-    # This owns exclusion only; active-agent mutation still belongs to EventLoop.
+    # Runtime-local admission for one synchronous coordination call per owner
+    # (a Handoff main Agent or TeamCoordinator). This does not own durable runs
+    # or active-agent mutation; those remain in their existing domains.
+    # @api private
     class AdmissionRegistry
+      # Construction has no side effects. Runtime returns the registered instance
+      # when callers concurrently supply candidates for the same key.
+      # @api private
+      def self.for(runtime)
+        runtime.__register_shutdown_participant(key: self, participant: new)
+      end
+
       def initialize
         @mutex = Mutex.new
         @cond = ConditionVariable.new
         @owners = {}
+        @draining = false
       end
 
       def admit!(coordinator)
         key = coordinator.object_id
         @mutex.synchronize do
+          if @draining
+            raise Phronomy::RuntimeShutdownError,
+              "Runtime is shutting down or failed; new Multi-Agent turns are not accepted"
+          end
           if @owners.key?(key)
             raise Phronomy::HandoffError,
               "a Multi-Agent turn is already active for this main Agent instance"
@@ -36,6 +50,12 @@ module Phronomy
         @mutex.synchronize { @owners.empty? }
       end
 
+      # Close admission atomically with respect to admit!, without waiting for
+      # admitted callers or calling back into Runtime. Repeated closure is safe.
+      def begin_draining
+        @mutex.synchronize { @draining = true }
+      end
+
       def wait_until_idle(deadline)
         @mutex.synchronize do
           until @owners.empty?

data/lib/phronomy/multi_agent/durable_subagent_coordinator.rb

@@ -16,13 +16,13 @@ module Phronomy
         children.each do |child|
           begin
             exact = tx.executions.load(child.fetch("execution_id"))
-          rescue Phronomy::Persistence::NotFoundError
+          rescue Phronomy::Storage::NotFoundError
             next
           end
-          raise Phronomy::Persistence::ConflictError, "Child owner mismatch" unless exact.agent_id == child.fetch("agent_id")
+          raise Phronomy::Storage::ConflictError, "Child owner mismatch" unless exact.agent_id == child.fetch("agent_id")
           child.merge!("state" => exact.status.to_s, "result_ref" => exact.result_ref, "error_ref" => exact.error_ref)
         end
-        Array(execution.metadata[Phronomy::Agent::RecoverySupport::TOOL_BATCH_METADATA_KEY]).each do |tool|
+        Array(execution.metadata[Phronomy::Agent::ExecutionMetadata::TOOL_BATCH_METADATA_KEY]).each do |tool|
           registration = parent.class.registered_subagents.find { |name, _| "dispatch_to_#{name}" == tool.fetch("tool_name") }
           next unless registration
           next if children.any? { |child| child.fetch("slot") == tool.fetch("tool_invocation_id") }
@@ -50,7 +50,7 @@ module Phronomy
         completion = Phronomy::TaskResult.deferred(name: "durable-subagent:#{tool_invocation_id}")
         preparation = runtime.offload.submit(on_full: :raise) do
           current = parent.persistence.executions.load(parent_execution_id)
-          raise Phronomy::Persistence::ConflictError, "Parent owner mismatch" unless current.agent_id == parent.agent_id
+          raise Phronomy::Storage::ConflictError, "Parent owner mismatch" unless current.agent_id == parent.agent_id
           snapshot = parent.persistence.contents.fetch_json(current.metadata.fetch(KEY))
           child = snapshot.fetch("children").find { |entry| entry.fetch("slot") == tool_invocation_id }
           raise Phronomy::ExecutionRehydrationRequiredError, "Missing reserved child slot" unless child
@@ -65,7 +65,7 @@ module Phronomy
             begin
               parent.persistence.agents.load(id)
               exists = true
-            rescue Phronomy::Persistence::NotFoundError
+            rescue Phronomy::Storage::NotFoundError
               exists = false
             end
             listener = parent.send(:_phronomy_event_listener)