phronomy 0.28.0 → 0.30.0

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/content_store/base.rb

@@ -28,13 +28,18 @@ module Phronomy
       def fetch_text(content_id)
         value = fetch(content_id).force_encoding(Encoding::UTF_8)
         unless value.valid_encoding?
-          raise IntegrityError, "content is not UTF-8: #{content_id}"
+          raise IntegrityError.new("content is not UTF-8: #{content_id}", code: "content.invalid_encoding")
         end
         value
       end
 
       def fetch_json(content_id)
-        Phronomy::CanonicalJSON.load(fetch(content_id))
+        bytes = fetch(content_id)
+        begin
+          Phronomy::CanonicalJSON.load(bytes)
+        rescue JSON::ParserError => error
+          raise IntegrityError.new("content is not JSON: #{content_id}", code: "content.invalid_json"), cause: error
+        end
       end
 
       def fetch_many(content_ids)

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,31 +90,25 @@ 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
 
       private
 
       def invoke_policy(policy, policy_input)
-        tracer = @tracer
-        span = tracer.start_span(
-          "context_policy",
-          agent_id: policy_input.agent_id,
-          execution_id: policy_input.execution_id,
-          call_sequence: policy_input.call_sequence,
-          policy_class: policy.class.name || policy.class.to_s,
-          instruction_count: policy_input.instruction.length,
-          knowledge_count: policy_input.knowledge.length,
-          tool_count: policy_input.tools.length,
-          conversation_group_count: policy_input.conversation.length
-        )
-        result = policy.call(policy_input)
-        tracer.finish_span(span)
-        result
-      rescue => error
-        tracer&.finish_span(span, error: error) if defined?(span) && span
-        raise
+        Phronomy::Tracing::Base.trace_with(
+          @tracer, "context_policy", record_output: false,
+          attributes: {agent_id: policy_input.agent_id,
+                       execution_id: policy_input.execution_id,
+                       call_sequence: policy_input.call_sequence,
+                       policy_class: policy.class.name || policy.class.to_s,
+                       instruction_count: policy_input.instruction.length,
+                       knowledge_count: policy_input.knowledge.length,
+                       tool_count: policy_input.tools.length,
+                       conversation_group_count: policy_input.conversation.length}
+        ) { [policy.call(policy_input), nil] }
       end
 
       def store_manifest(
@@ -124,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))
@@ -135,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/authentication_error.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative "transport_error"
+
+module Phronomy
+  module Embeddings
+    # Provider refusal; this classification alone does not authorize retries.
+    # @api public
+    class AuthenticationError < TransportError; end
+  end
+end

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.
@@ -40,8 +42,12 @@ module Phronomy
         opts[:provider] = @provider if @provider
         opts[:assume_model_exists] = true if @assume_model_exists
         ::RubyLLM.embed(text, **opts).vectors
-      rescue ::RubyLLM::Error => error
-        raise TransportError, error.message
+      rescue ::RubyLLM::UnauthorizedError, ::RubyLLM::ForbiddenError => error
+        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, ::Faraday::TimeoutError, ::Faraday::ConnectionFailed => error
+        raise TransportError.new(error.message), cause: error
       end
     end
   end

data/lib/phronomy/embeddings/rate_limit_error.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative "transport_error"
+
+module Phronomy
+  module Embeddings
+    # Provider refusal; this classification alone does not authorize retries.
+    # @api public
+    class RateLimitError < TransportError; end
+  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/execution/execution_cancellation_error.rb

@@ -6,9 +6,9 @@ module Phronomy
   class ExecutionCancellationError < CancellationError
     attr_reader :outcomes
 
-    def initialize(message = "Execution cancelled", outcomes:)
+    def initialize(message = "Execution cancelled", outcomes:, code: nil)
       @outcomes = outcomes
-      super(message)
+      super(message, code: code)
     end
   end
 end

data/lib/phronomy/execution/execution_timeout_error.rb

@@ -6,9 +6,9 @@ module Phronomy
   class ExecutionTimeoutError < TimeoutError
     attr_reader :outcomes
 
-    def initialize(message = "Execution timed out", outcomes:)
+    def initialize(message = "Execution timed out", outcomes:, code: nil)
       @outcomes = outcomes
-      super(message)
+      super(message, code: code)
     end
   end
 end

data/lib/phronomy/execution/task_result.rb

@@ -308,8 +308,13 @@ module Phronomy
     def deliver_completion_callback(callback, value, error)
       callback.call(value, error)
     rescue => callback_error
-      Phronomy::RuntimeSettings.current.logger&.error do
-        "[TaskResult] on_complete callback raised #{callback_error.class}: #{callback_error.message}"
+      begin
+        Phronomy::RuntimeSettings.current.logger&.error do
+          "[TaskResult] on_complete callback raised #{callback_error.class}: #{callback_error.message}"
+        end
+      rescue
+        # Reporting must not interrupt delivery to the remaining observers.
+        nil
       end
     end
 

data/lib/phronomy/filter/filter_block_error.rb

@@ -6,8 +6,8 @@ module Phronomy
   class FilterBlockError < Error
     attr_reader :filter
 
-    def initialize(message, filter: nil)
-      super(message)
+    def initialize(message, filter: nil, code: nil)
+      super(message, code: code)
       @filter = filter
     end
   end

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)

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