phronomy 0.22.0 → 0.24.0

data/lib/phronomy/agent/llm_input_manifest.rb

@@ -2,19 +2,98 @@
 
 module Phronomy
   module Agent
+    # ContentStore-backed durable codec boundary for one Provider input manifest.
+    # It is intentionally separate from Persistence::DurableRecord.
     class LLMInputManifest
-      VERSION = 1
+      VERSION = "0.1"
       CALL_MODES = %i[ask complete].freeze
+      SEGMENT_DELIVERIES = %w[ask_argument chat_message].freeze
 
       Segment = Data.define(
         :position, :category, :role, :content_ref, :delivery,
         :tool_call_id, :metadata
       ) do
         def initialize(**values)
+          delivery = values[:delivery]
+          if delivery.nil? || !SEGMENT_DELIVERIES.include?(delivery.to_s)
+            raise ArgumentError, "unknown Segment delivery: #{delivery.inspect}"
+          end
           super(**values.merge(metadata: Immutable.copy(values[:metadata] || {})))
           freeze
         end
 
+        def self.from_h(hash)
+          source = LLMInputManifest.send(
+            :strict_source!,
+            hash,
+            required: %w[position category content_ref delivery metadata],
+            optional: %w[role tool_call_id],
+            label: "LLMInputManifest segment"
+          )
+          label = "LLMInputManifest segment"
+          position = LLMInputManifest.send(
+            :require_nonnegative_integer_field!,
+            source,
+            "position",
+            label: label
+          )
+          category = LLMInputManifest.send(
+            :require_nonempty_string_field!,
+            source,
+            "category",
+            label: label
+          )
+          role = LLMInputManifest.send(
+            :require_optional_string_field!,
+            source,
+            "role",
+            label: label
+          )
+          content_ref = LLMInputManifest.send(
+            :require_nonempty_string_field!,
+            source,
+            "content_ref",
+            label: label
+          )
+          delivery = LLMInputManifest.send(
+            :require_nonempty_string_field!,
+            source,
+            "delivery",
+            label: label
+          )
+          unless SEGMENT_DELIVERIES.include?(delivery)
+            raise Phronomy::Persistence::SerializationError,
+              "LLMInputManifest segment delivery must be one of #{SEGMENT_DELIVERIES.inspect}, got #{delivery.inspect}"
+          end
+          tool_call_id = LLMInputManifest.send(
+            :require_optional_string_field!,
+            source,
+            "tool_call_id",
+            label: label
+          )
+          metadata = LLMInputManifest.send(
+            :require_hash_field!,
+            source,
+            "metadata",
+            label: label
+          )
+
+          new(
+            position: position,
+            category: category.to_sym,
+            role: role&.to_sym,
+            content_ref: content_ref,
+            delivery: delivery.to_sym,
+            tool_call_id: tool_call_id,
+            metadata: metadata
+          )
+        rescue Phronomy::Persistence::SerializationError
+          raise
+        rescue => error
+          raise Phronomy::Persistence::SerializationError,
+            "invalid LLMInputManifest segment: #{error.class}: #{error.message}"
+        end
+
         def to_h
           {
             "position" => position,
@@ -28,6 +107,15 @@ module Phronomy
         end
       end
 
+      REQUIRED_KEYS = %w[
+        version call_sequence call_mode assembly_policy_version segments
+        model_config_ref
+      ].freeze
+      OPTIONAL_KEYS = %w[
+        tool_definitions_ref response_schema_ref ruby_llm_version
+        adapter_name adapter_version
+      ].freeze
+
       attr_reader :version, :call_sequence, :call_mode,
         :assembly_policy_version, :segments,
         :model_config_ref, :tool_definitions_ref, :response_schema_ref,
@@ -46,7 +134,7 @@ module Phronomy
         adapter_version: nil,
         version: VERSION
       )
-        @version = Integer(version)
+        @version = String(version).freeze
         @call_sequence = Integer(call_sequence)
         @call_mode = call_mode.to_sym
         @assembly_policy_version = Integer(assembly_policy_version)
@@ -61,6 +149,93 @@ module Phronomy
         freeze
       end
 
+      # Current-format-only durable decoder. Historical format conversion is an
+      # explicit migration operation and is never attempted here. Unlike the
+      # Ruby construction API, this decoder never coerces durable field types.
+      def self.from_h(hash)
+        source = strict_source!(
+          hash,
+          required: REQUIRED_KEYS,
+          optional: OPTIONAL_KEYS,
+          label: "LLMInputManifest"
+        )
+        label = "LLMInputManifest"
+        version = source.fetch("version")
+        unless version.is_a?(String) && version == VERSION
+          raise Phronomy::Persistence::SerializationError,
+            "unsupported LLMInputManifest version: #{version.inspect}; " \
+            "current version is #{VERSION.inspect}"
+        end
+
+        call_sequence = require_positive_integer_field!(
+          source,
+          "call_sequence",
+          label: label
+        )
+        call_mode = require_enum_string_field!(
+          source,
+          "call_mode",
+          CALL_MODES.map(&:to_s),
+          label: label
+        )
+        assembly_policy_version = require_integer_field!(
+          source,
+          "assembly_policy_version",
+          label: label
+        )
+        segments = require_array_field!(source, "segments", label: label)
+          .map { |segment| Segment.from_h(segment) }
+        model_config_ref = require_nonempty_string_field!(
+          source,
+          "model_config_ref",
+          label: label
+        )
+        tool_definitions_ref = require_optional_string_field!(
+          source,
+          "tool_definitions_ref",
+          label: label
+        )
+        response_schema_ref = require_optional_string_field!(
+          source,
+          "response_schema_ref",
+          label: label
+        )
+        ruby_llm_version = require_optional_string_field!(
+          source,
+          "ruby_llm_version",
+          label: label
+        )
+        adapter_name = require_optional_string_field!(
+          source,
+          "adapter_name",
+          label: label
+        )
+        adapter_version = require_optional_string_field!(
+          source,
+          "adapter_version",
+          label: label
+        )
+
+        new(
+          version: version,
+          call_sequence: call_sequence,
+          call_mode: call_mode.to_sym,
+          assembly_policy_version: assembly_policy_version,
+          segments: segments,
+          model_config_ref: model_config_ref,
+          tool_definitions_ref: tool_definitions_ref,
+          response_schema_ref: response_schema_ref,
+          ruby_llm_version: ruby_llm_version,
+          adapter_name: adapter_name,
+          adapter_version: adapter_version
+        )
+      rescue Phronomy::Persistence::SerializationError
+        raise
+      rescue => error
+        raise Phronomy::Persistence::SerializationError,
+          "invalid LLMInputManifest: #{error.class}: #{error.message}"
+      end
+
       def referenced_content_refs
         ([model_config_ref, tool_definitions_ref, response_schema_ref] +
           segments.map(&:content_ref)).compact.uniq.freeze
@@ -82,9 +257,109 @@ module Phronomy
         }.compact
       end
 
+      class << self
+        private
+
+        def strict_source!(hash, required:, optional:, label:)
+          unless hash.is_a?(Hash)
+            raise Phronomy::Persistence::SerializationError,
+              "#{label} must be a Hash"
+          end
+          unless hash.keys.all? { |key| key.is_a?(String) }
+            raise Phronomy::Persistence::SerializationError,
+              "#{label} keys must all be String"
+          end
+
+          actual = hash.keys
+          missing = required - actual
+          unknown = actual - (required + optional)
+          unless missing.empty? && unknown.empty?
+            details = []
+            details << "missing=#{missing.inspect}" unless missing.empty?
+            details << "unknown=#{unknown.inspect}" unless unknown.empty?
+            raise Phronomy::Persistence::SerializationError,
+              "#{label} schema mismatch (#{details.join(", ")})"
+          end
+          Phronomy::CanonicalJSON.dump(hash)
+          hash
+        rescue ArgumentError => error
+          raise Phronomy::Persistence::SerializationError,
+            "#{label} is not canonical JSON compatible: #{error.message}"
+        end
+
+        def require_integer_field!(hash, key, label:)
+          value = hash.fetch(key)
+          return value if value.is_a?(Integer)
+
+          raise Phronomy::Persistence::SerializationError,
+            "#{label} #{key} must be an Integer"
+        end
+
+        def require_positive_integer_field!(hash, key, label:)
+          value = hash.fetch(key)
+          return value if value.is_a?(Integer) && value.positive?
+
+          raise Phronomy::Persistence::SerializationError,
+            "#{label} #{key} must be a positive Integer"
+        end
+
+        def require_nonnegative_integer_field!(hash, key, label:)
+          value = hash.fetch(key)
+          return value if value.is_a?(Integer) && value >= 0
+
+          raise Phronomy::Persistence::SerializationError,
+            "#{label} #{key} must be a non-negative Integer"
+        end
+
+        def require_nonempty_string_field!(hash, key, label:)
+          value = hash.fetch(key)
+          return value if value.is_a?(String) && !value.empty?
+
+          raise Phronomy::Persistence::SerializationError,
+            "#{label} #{key} must be a non-empty String"
+        end
+
+        def require_optional_string_field!(hash, key, label:)
+          value = hash[key]
+          return value if value.nil? || value.is_a?(String)
+
+          raise Phronomy::Persistence::SerializationError,
+            "#{label} #{key} must be a String or nil"
+        end
+
+        def require_enum_string_field!(hash, key, allowed, label:)
+          value = hash.fetch(key)
+          return value if value.is_a?(String) && allowed.include?(value)
+
+          raise Phronomy::Persistence::SerializationError,
+            "#{label} #{key} must be one of #{allowed.inspect}"
+        end
+
+        def require_array_field!(hash, key, label:)
+          value = hash.fetch(key)
+          return value if value.is_a?(Array)
+
+          raise Phronomy::Persistence::SerializationError,
+            "#{label} #{key} must be an Array"
+        end
+
+        def require_hash_field!(hash, key, label:)
+          value = hash.fetch(key)
+          return value if value.is_a?(Hash)
+
+          raise Phronomy::Persistence::SerializationError,
+            "#{label} #{key} must be a Hash"
+        end
+      end
+
       private
 
       def validate!
+        unless version == VERSION
+          raise Phronomy::ConfigurationError,
+            "unsupported LLMInputManifest version: #{version.inspect}; " \
+            "current version is #{VERSION.inspect}"
+        end
         raise ArgumentError, "invalid manifest call mode: #{call_mode.inspect}" unless CALL_MODES.include?(call_mode)
         raise ArgumentError, "call_sequence must be positive" unless call_sequence.positive?
         expected = (0...segments.length).to_a

data/lib/phronomy/agent/llm_operation_result.rb

@@ -2,20 +2,25 @@
 
 module Phronomy
   module Agent
-    # Immutable carrier for one LLM adapter operation outcome.
+    # Immutable carrier for one Provider operation outcome.
     #
-    # Worker/timer threads create this value without mutating AgentInvocation.
-    # AgentInvocationSessionBuilder posts it as :llm_completed or :llm_failed,
-    # and AgentInvocation applies it on the EventLoop thread.
+    # The Provider Call identity is allocated on EventLoop before transport starts.
+    # Worker completion carries that semantic identity back to the owning
+    # FSMSession, which validates it against the currently active call before
+    # applying any live state.
     #
     # @api private
     class LLMOperationResult
-      attr_reader :response, :error, :streaming
+      attr_reader :llm_call_id, :response, :error, :streaming
 
-      def initialize(response: nil, error: nil, streaming: false)
+      def initialize(llm_call_id:, response: nil, error: nil, streaming: false)
+        id = llm_call_id&.to_s
+        raise ArgumentError, "LLMOperationResult requires llm_call_id" if id.nil? || id.empty?
+
+        @llm_call_id = id.freeze
         @response = response
         @error = error
-        @streaming = streaming
+        @streaming = !!streaming
         freeze
       end
     end

data/lib/phronomy/agent/phase_machine_builder.rb

@@ -4,12 +4,6 @@ require "state_machines"
 
 module Phronomy
   module Agent
-    # Compiles AgentInvocation phase topology.
-    #
-    # Async completion is represented by explicit FSM events. This builder does
-    # not await Tasks or register Task callbacks.
-    #
-    # @api private
     class PhaseMachineBuilder
       TOOL_EVENTS = %i[
         tool_authorized
@@ -43,6 +37,7 @@ module Phronomy
             state :recording_tool_results
             state :suspended
             state :output_filtering
+            state :handed_off
             state :completed
             state :blocked
             state :failed
@@ -70,7 +65,6 @@ module Phronomy
                 if: ->(machine) { machine.context&.ready_to_dispatch? }
               transition evaluating_tools: :waiting_for_tools
 
-              transition dispatching_tools: :evaluating_tools
               transition recording_tool_results: :calling_llm
 
               transition output_filtering: :completed,
@@ -80,6 +74,12 @@ module Phronomy
             end
 
             event :llm_completed do
+              transition calling_llm: :failed,
+                if: ->(machine) { machine.context&.callback_failed? }
+              transition calling_llm: :failed,
+                if: ->(machine) { machine.context&.handoff_failed? }
+              transition calling_llm: :handed_off,
+                if: ->(machine) { machine.context&.handoff_requested? }
               transition calling_llm: :starting_tools,
                 if: ->(machine) { machine.context&.tool_call_pending? }
               transition calling_llm: :output_filtering
@@ -89,6 +89,18 @@ module Phronomy
               transition calling_llm: :failed
             end
 
+            event :llm_setup_failed do
+              transition calling_llm: :failed
+            end
+
+            event :tool_setup_failed do
+              transition dispatching_tools: :failed
+            end
+
+            event :tool_dispatch_prepared do
+              transition dispatching_tools: :evaluating_tools
+            end
+
             TOOL_EVENTS.each do |event_name|
               event event_name do
                 transition waiting_for_tools: :evaluating_tools

data/lib/phronomy/agent/provider_call_outcome.rb

@@ -3,11 +3,10 @@
 module Phronomy
   module Agent
     # Immutable, Phronomy-owned snapshot of one completed Provider assistant output.
-    # It is captured before Agent-owned Tool execution begins, so durable logging
-    # never depends on RubyLLM's later control flow or Application callbacks.
     ProviderCallOutcome = Data.define(:role, :content, :tool_calls, :usage, :metadata) do
       def self.capture(message)
         return if message.nil?
+        return message if message.is_a?(self)
 
         calls = if message.respond_to?(:tool_calls) && message.tool_calls
           source = message.tool_calls.respond_to?(:values) ? message.tool_calls.values : Array(message.tool_calls)
@@ -32,6 +31,17 @@ module Phronomy
         )
       end
 
+      def self.from_h(hash)
+        source = hash.to_h { |key, value| [key.to_s, value] }
+        new(
+          role: source.fetch("role", "assistant"),
+          content: source["content"],
+          tool_calls: source.fetch("tool_calls", []),
+          usage: source.fetch("usage", {}),
+          metadata: source.fetch("metadata", {})
+        )
+      end
+
       def self.tool_call_hash(call)
         return call.to_h if call.respond_to?(:to_h)
 
@@ -54,11 +64,7 @@ module Phronomy
         when String, Integer, Float, TrueClass, FalseClass, NilClass
           value
         else
-          if value.respond_to?(:to_h)
-            normalize(value.to_h)
-          else
-            value.to_s
-          end
+          value.respond_to?(:to_h) ? normalize(value.to_h) : value.to_s
         end
       end
       private_class_method :normalize
@@ -78,6 +84,16 @@ module Phronomy
         freeze
       end
 
+      def to_h
+        {
+          "role" => role&.to_s,
+          "content" => content,
+          "tool_calls" => tool_calls,
+          "usage" => usage,
+          "metadata" => metadata
+        }.compact
+      end
+
       def content_present?
         !content.nil? && !(content.respond_to?(:empty?) && content.empty?)
       end

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

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    class RecoveryCoordinator
+      # Both resolution apply and restart use this interpretation of saved facts.
+      # Runtime tasks and sessions are projections, never continuation authority.
+      # @api private
+      module Continuation
+        private
+
+        def recovery_action(execution)
+          return :framework_tools if framework_batch?(execution)
+
+          case execution.phase.to_sym
+          when :recovery_provider_completed
+            execution.metadata["framework_calls_pending"] ? :framework_calls : :output
+          when :recovery_tools_completed
+            execution.metadata["framework_calls_pending"] ? :framework_calls : :followup
+          when :recovery_resolved_failed
+            :failed_terminal
+          else
+            :resolution_required
+          end
+        end
+
+        # Read durable inputs before entering EventLoop. The returned messages are
+        # operation-local projections transferred to the new invocation, never a
+        # shared cache or a second source of continuation decisions.
+        def prepare_recovery_material(execution, projection: nil)
+          action = recovery_action(execution)
+          suspended = execution.status == :suspended || execution.phase.to_sym == :resuming
+          return if !suspended && %i[resolution_required failed_terminal].include?(action)
+
+          unless projection
+            _manifest, projection = RecoverySupport.materialize_projection(agent, execution.metadata.fetch("manifest_ref"))
+          end
+          records = execution.working_records.select { |record| %i[assistant_message tool_message].include?(record.kind.to_sym) }
+          materializer = RubyLLMMaterializer.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 = RecoverySupport.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)
+        end
+
+        def continue_recovery_on_event_loop(execution, completion, material:)
+          event_loop = @runtime.event_loop
+          action = recovery_action(execution)
+          if action == :resolution_required
+            event_loop.mark_agent_execution_admission(agent.agent_id,
+              execution_id: execution.execution_id, state: :recovery_required)
+            deliver_resolution_required(execution, coordination_recovery_descriptor(execution))
+            completion.complete({execution_id: execution.execution_id,
+                                 execution_revision: execution.execution_revision,
+                                 recovery: :resolution_required}.freeze)
+            return
+          end
+
+          observe_recovery_execution(completion, execution)
+          main = agent.send(:execution_coordinator_for, agent.__coordination_config)
+          projection = event_loop.agent_execution_state(execution.execution_id).runtime_projection
+          if action == :failed_terminal
+            invocation = build_failed_recovery_invocation(execution, main)
+          else
+            projection = material.projection
+            invocation = if action == :framework_tools
+              RecoverySupport.build_invocation_for_suspended(agent, execution, projection, main,
+                agent.send(:_phronomy_event_listener), assistant_message: material.assistant_message)
+            else
+              RecoverySupport.build_chat_for_recovery(agent, execution, projection, main,
+                agent.send(:_phronomy_event_listener), messages: material.messages)
+            end
+            if execution.phase.to_sym == :recovery_provider_completed
+              invocation.output, invocation.usage = material.output, material.usage
+            end
+            prepare_saved_provider_calls(execution, invocation, material.assistant_message) if action == :framework_calls
+          end
+
+          event_loop.replace_agent_execution(execution.execution_id, execution: execution,
+            runtime_projection: projection, invocation: invocation, fsm_session_id: nil)
+          if action == :failed_terminal
+            failure = execution.metadata.dig(RecoverySupport::RECOVERY_METADATA_KEY, "failure") ||
+              {"class" => "Phronomy::Error", "message" => "Recovery-resolved failure"}
+            main.send(:begin_terminal_commit_on_event_loop,
+              event_loop.agent_execution_state(execution.execution_id), completion, invocation,
+              RecoverySupport.error_from_failure(failure), fsm_session_id: nil)
+            return
+          end
+
+          event_loop.mark_agent_execution_admission(agent.agent_id,
+            execution_id: execution.execution_id, state: :executing)
+          case action
+          when :framework_tools
+            event_loop.register_agent_completion_waiter(execution.execution_id, completion)
+            main.send(:start_framework_tools_on_event_loop, execution.execution_id, completion)
+          when :framework_calls, :output
+            # Re-enter the ordinary FSM before output filtering so its failures
+            # settle through the same durable terminal barrier as a live call.
+            start_recovery_session(event_loop, main, execution, invocation, completion,
+              resume_event: :llm_completed, resume_phase: :calling_llm)
+          when :followup
+            start_recovery_session(event_loop, main, execution, invocation, completion,
+              resume_event: :state_completed, resume_phase: :recording_tool_results)
+          end
+        end
+
+        def prepare_saved_provider_calls(execution, invocation, message)
+          record = RecoverySupport.latest_assistant_record(execution)
+          calls = message.tool_calls.respond_to?(:values) ? message.tool_calls.values : Array(message.tool_calls)
+          framework_calls = calls.select { |call| agent.__framework_call?(call.name) }
+          if framework_calls.empty?
+            raise Phronomy::ExecutionRehydrationRequiredError, "Saved framework call wiring is missing"
+          end
+          invocation.accept_tool_calls!(framework_calls, llm_call_id: record.llm_call_id)
+        end
+
+        def build_failed_recovery_invocation(execution, main)
+          Phronomy::Agent::AgentInvocation.new(agent: agent, input: nil,
+            config: {execution_id: execution.execution_id, phronomy_execution_coordinator: main},
+            event_listener: agent.send(:_phronomy_event_listener),
+            mode: (execution.metadata[RecoverySupport::INVOCATION_MODE_KEY] || "invoke").to_sym,
+            execution_id: execution.execution_id)
+        end
+
+        def start_recovery_session(event_loop, main, execution, invocation, completion, resume_event:, resume_phase:)
+          session = AgentInvocationSessionBuilder.build_for_resume(agent_invocation: invocation,
+            resume_event: resume_event, resume_phase: resume_phase, runtime: @runtime)
+          event_loop.replace_agent_execution(execution.execution_id, invocation: invocation, fsm_session_id: session.id)
+          event_loop.register_agent_completion_waiter(execution.execution_id, completion)
+          source = Phronomy::Task.deferred(name: "#{completion.name}-source")
+          source.on_complete do |completed, error|
+            main.send(:finish_on_event_loop, execution.execution_id, completion,
+              completed || session.context, error, fsm_session_id: session.id)
+          end
+          event_loop.register(session, completion: source)
+        end
+
+        def deliver_resolution_required(execution, descriptor)
+          unless descriptor
+            raise Phronomy::ExecutionRehydrationRequiredError,
+              "Recovery state has no current unresolved subject"
+          end
+          listener = agent.send(:_phronomy_event_listener)
+          unless listener
+            raise Phronomy::ConfigurationError,
+              "Recovery resolution requires an Agent on_event listener"
+          end
+          payload = RecoverySupport.event_payload(
+            execution,
+            descriptor
+          )
+          callback_error = agent.send(
+            :_deliver_stream_event,
+            listener,
+            StreamEvent.new(
+              type: :recovery_resolution_required,
+              payload: payload
+            )
+          )
+          if callback_error
+            raise agent.send(
+              :_build_stream_callback_error,
+              event_type: :recovery_resolution_required,
+              callback_error: callback_error,
+              result: payload
+            )
+          end
+          nil
+        end
+      end
+    end
+  end
+end