phronomy 0.26.0 → 0.27.0

data/lib/phronomy/agent/execution/initial_preparation.rb

@@ -0,0 +1,421 @@
+# frozen_string_literal: true
+
+require_relative "../../engine/concurrency/worker_input_restricted"
+
+require "securerandom"
+require "time"
+
+module Phronomy
+  module Agent
+    # Admits and prepares an execution, or replays its saved preparation inputs.
+    # Runtime admission, live-state application and result delivery stay with
+    # the execution owner. Per-operation state is kept in local variables.
+    # @api private
+    class InitialPreparation
+      include Phronomy::Concurrency::WorkerInputRestricted
+
+      Command = Data.define(
+        :root, :journal_records, :input, :config, :preparation_replayable
+      )
+      RecoveryCommand = Data.define(:execution, :root, :journal_records)
+      Result = Data.define(
+        :execution, :root, :runtime_projection, :filtered_input,
+        :config, :appended_records, :error, :admission_outcome
+      )
+
+      # @api private
+      def initialize(agent:, persistence:)
+        @agent = agent
+        @persistence = persistence
+      end
+
+      # @api private
+      def prepare(operation)
+        begin
+          raw_message = @agent.send(:extract_message, operation.input)
+        rescue => error
+          return unadmitted_result(operation, error, :not_established)
+        end
+
+        begin
+          execution, active_root = admit_execution(
+            raw_message,
+            root: operation.root,
+            mode: (operation.config[:phronomy_recovery_mode] || :invoke).to_sym,
+            config: operation.config,
+            preparation_replayable: operation.preparation_replayable
+          )
+        rescue Phronomy::AgentBusyError => error
+          # A durable nonterminal execution keeps Runtime admission fail-closed
+          # until recovery can establish its lineage, including after F4 loss.
+          return unadmitted_result(operation, error, :recovery_required)
+        rescue Phronomy::Storage::ConflictError,
+          Phronomy::Storage::NotFoundError,
+          Phronomy::Storage::SerializationError,
+          ArgumentError,
+          Phronomy::ConfigurationError => error
+          return unadmitted_result(operation, error, :not_established)
+        rescue => error
+          return unadmitted_result(operation, error, :outcome_unknown)
+        end
+
+        prepare_admitted(
+          input: operation.input,
+          config: operation.config,
+          execution: execution,
+          active_root: active_root,
+          journal_records: operation.journal_records
+        )
+      end
+
+      # @api private
+      def recover(operation)
+        execution = operation.execution
+        unless execution.metadata["preparation_replayable"] == true
+          raise Phronomy::ExecutionRehydrationRequiredError,
+            "execution #{execution.execution_id} has no replay-safe initial preparation contract"
+        end
+
+        input = @persistence.contents.fetch_text(execution.metadata.fetch("current_input_ref"))
+        config = recovered_config(execution)
+        prepare_admitted(
+          input: input,
+          config: config,
+          execution: execution,
+          active_root: operation.root,
+          journal_records: operation.journal_records
+        )
+      end
+
+      private
+
+      def unadmitted_result(operation, error, outcome)
+        Result.new(
+          execution: nil,
+          root: operation.root,
+          runtime_projection: nil,
+          filtered_input: nil,
+          config: operation.config,
+          appended_records: [].freeze,
+          error: translated(error),
+          admission_outcome: outcome
+        )
+      end
+
+      def prepare_admitted(input:, config:, execution:, active_root:, journal_records:)
+        current_execution = execution
+        begin
+          filtered_input = filter_input(input, config)
+          staged = stage_filtered_input(current_execution, active_root, filtered_input)
+          assembler, prepared = prepare_context(staged, active_root, filtered_input, config, journal_records)
+          active_execution, manifest, manifest_ref = commit_preparation(
+            staged, active_root, assembler, prepared
+          )
+          # Advance the failure base only after the commit response is known.
+          # F1 response loss must not be reported as a confirmed terminal result.
+          current_execution = active_execution
+          projection = RubyLLMMaterializer.new(
+            agent: @agent, persistence: @persistence
+          ).materialize(manifest: manifest, manifest_ref: manifest_ref)
+          Result.new(
+            execution: active_execution,
+            root: active_root,
+            runtime_projection: projection,
+            filtered_input: filtered_input,
+            config: config,
+            appended_records: [].freeze,
+            error: nil,
+            admission_outcome: :active
+          )
+        rescue => error
+          preparation_failure_result(current_execution, active_root, config, error)
+        end
+      end
+
+      def filter_input(input, config)
+        @agent.send(:check_cancellation!, config, "invocation cancelled before input filtering")
+        filtered = @agent.send(:run_input_filters!, input)
+        @agent.send(:check_cancellation!, config, "invocation cancelled before context assembly")
+        filtered
+      end
+
+      def stage_filtered_input(execution, root, filtered_input)
+        message = @agent.send(:extract_message, filtered_input)
+        # Content-addressed source material may precede Policy. Mutable execution
+        # and Agent records are only advanced by the later commit transaction.
+        filtered_ref = @persistence.contents.put_text(message)
+        record = JournalRecord.new(
+          agent_id: @agent.agent_id,
+          execution_id: execution.execution_id,
+          kind: :external_message,
+          channel: :external,
+          role: :user,
+          content_ref: filtered_ref,
+          context_generation: root.transcript_generation,
+          context_candidate: true,
+          metadata: {"handoff_policy_category" => "current_request"}
+        )
+        execution.with(
+          execution_revision: execution.execution_revision,
+          working_records: execution.working_records + [record],
+          metadata: execution.metadata.merge(
+            "current_input_ref" => filtered_ref,
+            "current_input_record_id" => record.record_id
+          )
+        )
+      end
+
+      def prepare_context(staged, root, input, config, journal_records)
+        assembler = ContextAssembler.new(
+          agent: @agent, persistence: @persistence, journal_records: journal_records
+        )
+        prepared = assembler.prepare_initial(
+          input: input,
+          agent_root: root,
+          execution: staged,
+          config: config,
+          patch: @agent.send(:run_before_llm_input_hooks, call_sequence: 1, config: config)
+        )
+        @agent.send(:check_cancellation!, config, "invocation cancelled after context policy")
+        [assembler, prepared]
+      end
+
+      def commit_preparation(staged, root, assembler, prepared)
+        active = manifest = manifest_ref = nil
+        @persistence.transaction do |tx|
+          assert_local_durable_base!(tx, root)
+          manifest, manifest_ref = assembler.finalize(prepared, persistence: tx)
+          active = execution_with_initial_manifest(staged, manifest_ref)
+          tx.executions.save(
+            staged.execution_id,
+            expected_revision: staged.execution_revision,
+            execution: active
+          )
+        end
+        [active, manifest, manifest_ref]
+      end
+
+      def execution_with_initial_manifest(staged, manifest_ref)
+        staged.with(
+          status: :active,
+          phase: :calling_llm,
+          metadata: staged.metadata.merge(
+            "base_manifest_ref" => manifest_ref,
+            "manifest_ref" => manifest_ref,
+            "manifest_refs" => [manifest_ref]
+          )
+        )
+      end
+
+      def admit_execution(raw_message, root:, mode: :invoke, config: {}, preparation_replayable: false)
+        if root.lifecycle_status == :closed
+          raise Phronomy::Error, "agent is closed: #{@agent.agent_id}"
+        end
+
+        execution = next_root = nil
+        preparation_metadata = initial_preparation_metadata(mode.to_sym, preparation_replayable)
+        @persistence.transaction do |tx|
+          execution = build_admitted_execution(
+            tx, raw_message, root: root, config: config,
+            preparation_metadata: preparation_metadata
+          )
+          validate_coordination_admission!(tx, execution)
+          tx.executions.create_active(execution)
+          next_root = root.with(
+            agent_revision: root.agent_revision + 1,
+            lifecycle_status: :active
+          )
+          tx.agents.save(root.agent_id, expected_revision: root.agent_revision, root: next_root)
+        end
+        [execution, next_root]
+      end
+
+      def initial_preparation_metadata(mode, replayable)
+        {
+          "preparation_replayable" => !!replayable,
+          ExecutionMetadata::CONTRACT_VERSION_KEY => ExecutionMetadata::CONTRACT_VERSION,
+          ExecutionMetadata::INVOCATION_MODE_KEY => mode.to_s,
+          ExecutionMetadata::PENDING_LLM_ID_KEY => SecureRandom.uuid.to_s.freeze,
+          ExecutionMetadata::PENDING_LLM_STARTED_AT_KEY => Time.now.utc.iso8601(6).freeze
+        }
+      end
+
+      def build_admitted_execution(tx, raw_message, root:, config:, preparation_metadata:)
+        input_ref = tx.contents.put_text(raw_message)
+        durable_context_ref = if config.key?(:durable_context)
+          tx.contents.put_json(config.fetch(:durable_context))
+        end
+        input_record = JournalRecord.new(
+          agent_id: @agent.agent_id,
+          kind: :input_received,
+          channel: :external,
+          role: :user,
+          content_ref: input_ref,
+          context_generation: root.transcript_generation,
+          context_candidate: false
+        )
+        execution = AgentExecution.start(
+          agent_root: root,
+          input_record: input_record,
+          execution_id: config[:phronomy_reserved_execution_id] || SecureRandom.uuid,
+          metadata: {
+            "coordination" => config[:phronomy_coordination],
+            "current_input_ref" => input_ref,
+            "durable_context_ref" => durable_context_ref
+          }.merge(preparation_metadata).compact
+        )
+        input_record = JournalRecord.from_h(input_record.to_h.merge("execution_id" => execution.execution_id))
+        execution.with(execution_revision: 0, working_records: [input_record])
+      end
+
+      def validate_coordination_admission!(tx, execution)
+        owner = execution.metadata["coordination"]
+        return unless owner
+
+        case owner.fetch("kind")
+        when "team" then validate_team_admission!(tx, execution, owner)
+        when "subagent" then validate_subagent_admission!(tx, execution, owner)
+        when "handoff" then validate_handoff_admission!(tx, execution, owner)
+        else
+          raise Phronomy::ConfigurationError, "Unknown coordination owner kind"
+        end
+      end
+
+      def validate_team_admission!(tx, execution, owner)
+        team = tx.team_executions.load(owner.fetch("team_execution_id"))
+        unless team.team_id == owner.fetch("team_id") && team.active? && !team.metadata["cancel_requested"]
+          raise Phronomy::CancellationError, "Team run is no longer dispatchable"
+        end
+        slot = if owner.fetch("slot") == "coordinator"
+          team.coordinator
+        else
+          assignment = team.assignments.find { |entry| entry.fetch("task_id") == owner.fetch("slot") }
+          worker = assignment && team.workers.fetch(assignment.fetch("worker"))
+          worker&.merge("execution_id" => assignment.fetch("execution_id"))
+        end
+        unless slot && slot.fetch("execution_id") == execution.execution_id && slot.fetch("agent_id") == execution.agent_id
+          raise Phronomy::Storage::ConflictError, "Team reserved child identity mismatch"
+        end
+      end
+
+      def validate_subagent_admission!(tx, execution, owner)
+        parent = tx.executions.load(owner.fetch("parent_execution_id"))
+        unless parent.agent_id == owner.fetch("parent_agent_id") && parent.active? && !parent.metadata["coordination_cancel_requested"]
+          raise Phronomy::CancellationError, "Parent run is no longer dispatchable"
+        end
+        snapshot = tx.contents.fetch_json(parent.metadata.fetch("multi_agent_coordination_ref"))
+        slot = snapshot.fetch("children").find { |entry| entry.fetch("slot") == owner.fetch("slot") }
+        unless slot && slot.fetch("agent_id") == execution.agent_id && slot.fetch("execution_id") == execution.execution_id
+          raise Phronomy::Storage::ConflictError, "Parent reserved child identity mismatch"
+        end
+      end
+
+      def validate_handoff_admission!(tx, execution, owner)
+        routing = tx.handoff_states.load(owner.fetch("main_agent_id"))
+        unless routing && routing.active_agent_id == execution.agent_id
+          raise Phronomy::Storage::ConflictError, "Handoff responsibility changed before admission"
+        end
+        if Array(routing.metadata["cancelled_execution_ids"]).include?(execution.execution_id)
+          raise Phronomy::CancellationError, "Handoff reservation was cancelled"
+        end
+        if routing.phase != "stable" && routing.pending_target_execution_id != execution.execution_id
+          raise Phronomy::Storage::ConflictError, "Handoff reserved Target identity mismatch"
+        end
+      end
+
+      def recovered_config(execution)
+        mode = (execution.metadata[ExecutionMetadata::INVOCATION_MODE_KEY] || "invoke").to_sym
+        config = {phronomy_recovery_mode: mode}.merge(@agent.__coordination_config)
+        if execution.metadata.key?("durable_context_ref")
+          context = @persistence.contents.fetch_json(execution.metadata.fetch("durable_context_ref"))
+          unless context.is_a?(Hash)
+            raise Phronomy::ExecutionRehydrationRequiredError,
+              "execution #{execution.execution_id} has a non-Hash durable_context"
+          end
+          Phronomy::Values::Immutable.validate_canonical_json!(context, label: "Recovered durable_context")
+          config[:durable_context] = Phronomy::Values::Immutable.copy(context)
+        end
+        config.freeze
+      end
+
+      def preparation_failure_result(execution, root, config, error)
+        failure = commit_preparation_failure(execution, root, error)
+        Result.new(
+          execution: failure.fetch(:execution),
+          root: failure.fetch(:root),
+          runtime_projection: nil,
+          filtered_input: nil,
+          config: config,
+          appended_records: failure.fetch(:appended_records),
+          error: failure.fetch(:error),
+          admission_outcome: :terminal
+        )
+      end
+
+      def commit_preparation_failure(execution, root, error)
+        translated_error = translated(error)
+        failed = next_root = appended = nil
+        @persistence.transaction do |tx|
+          error_ref = tx.contents.put_json(
+            "class" => translated_error.class.name,
+            "message" => translated_error.message
+          )
+          status = ExecutionFailure.status_for(translated_error)
+          records = preparation_failure_records(execution, root, status, error_ref)
+          appended = tx.journals.append(
+            root.agent_id, expected_position: root.journal_position, records: records
+          )
+          failed = execution.with(
+            status: status,
+            phase: status,
+            working_records: [],
+            error_ref: error_ref,
+            terminal_reason: translated_error.class.name
+          )
+          tx.executions.save(
+            execution.execution_id, expected_revision: execution.execution_revision, execution: failed
+          )
+          next_root = root.with(
+            agent_revision: root.agent_revision + 1,
+            journal_position: root.journal_position + appended.length,
+            lifecycle_status: :idle
+          )
+          tx.agents.save(root.agent_id, expected_revision: root.agent_revision, root: next_root)
+        end
+        {
+          error: translated_error,
+          execution: failed,
+          root: next_root,
+          appended_records: Array(appended).freeze
+        }.freeze
+      end
+
+      def preparation_failure_records(execution, root, status, error_ref)
+        records = execution.working_records.map do |record|
+          JournalRecord.from_h(record.to_h.merge("context_candidate" => false))
+        end
+        records << JournalRecord.new(
+          agent_id: @agent.agent_id,
+          execution_id: execution.execution_id,
+          kind: ExecutionFailure.journal_kind_for(status),
+          channel: :audit,
+          content_ref: error_ref,
+          context_generation: root.transcript_generation,
+          context_candidate: false
+        )
+      end
+
+      def assert_local_durable_base!(tx, root)
+        tx.assert_agent_watermark!(
+          agent_id: root.agent_id,
+          agent_revision: root.agent_revision,
+          journal_position: root.journal_position
+        )
+      end
+
+      def translated(error)
+        @agent.send(:_translated_error, error)
+      end
+    end
+  end
+end

data/lib/phronomy/agent/execution/invocation_transitions.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    # Agent phase vocabulary and ordered external transitions. Both the phase
+    # machine and FSMSession read this definition; Engine has no Agent policy.
+    # Automatic transition behavior and entry actions retain their own owners.
+    # @api private
+    module InvocationTransitions
+      ENTRY_POINT = :idle
+
+      AUTO_STATE_SET = {
+        idle: true,
+        filtering_input: true,
+        building_context: true,
+        starting_tools: true,
+        evaluating_tools: true,
+        recording_tool_results: true,
+        output_filtering: true
+      }.freeze
+
+      DECLARED_STATES = %i[
+        idle filtering_input building_context calling_llm starting_tools
+        evaluating_tools waiting_for_tools dispatching_tools
+        recording_tool_results suspended output_filtering handed_off completed blocked failed
+      ].freeze
+
+      WAIT_STATES = %i[suspended].freeze
+
+      TOOL_EVENTS = %i[
+        tool_authorized
+        tool_approval_required
+        tool_completed
+        tool_failed
+        tool_rejected
+        tool_cancelled
+      ].freeze
+
+      EXTERNAL_EVENTS = begin
+        tool_transitions = TOOL_EVENTS.to_h do |event_name|
+          [event_name, [{from: :waiting_for_tools, to: :evaluating_tools, guard: nil}]]
+        end
+
+        events = tool_transitions.merge(
+          llm_completed: [
+            {from: :calling_llm, to: :failed, guard: ->(ctx) { ctx.callback_failed? }},
+            {from: :calling_llm, to: :failed, guard: ->(ctx) { ctx.handoff_failed? }},
+            {from: :calling_llm, to: :handed_off, guard: ->(ctx) { ctx.handoff_requested? }},
+            {from: :calling_llm, to: :starting_tools, guard: ->(ctx) { ctx.tool_call_pending? }},
+            {from: :calling_llm, to: :output_filtering, guard: nil}
+          ],
+          llm_failed: [
+            {from: :calling_llm, to: :failed, guard: nil}
+          ],
+          llm_setup_failed: [
+            {from: :calling_llm, to: :failed, guard: nil}
+          ],
+          tool_setup_failed: [
+            {from: :dispatching_tools, to: :failed, guard: nil}
+          ],
+          tool_dispatch_prepared: [
+            {from: :dispatching_tools, to: :evaluating_tools, guard: nil}
+          ],
+          resume: [
+            {from: :suspended, to: :waiting_for_tools, guard: nil}
+          ],
+          application_callback_failed: [
+            {from: :filtering_input, to: :failed, guard: nil},
+            {from: :building_context, to: :failed, guard: nil},
+            {from: :calling_llm, to: :failed, guard: nil},
+            {from: :starting_tools, to: :failed, guard: nil},
+            {from: :evaluating_tools, to: :failed, guard: nil},
+            {from: :waiting_for_tools, to: :failed, guard: nil},
+            {from: :dispatching_tools, to: :failed, guard: nil},
+            {from: :recording_tool_results, to: :failed, guard: nil},
+            {from: :output_filtering, to: :failed, guard: nil}
+          ]
+        )
+        events.each_value do |transitions|
+          transitions.each(&:freeze).freeze
+        end
+        events.freeze
+      end
+    end
+  end
+end

data/lib/phronomy/agent/{phase_machine_builder.rb → execution/phase_machine_builder.rb}

@@ -5,15 +5,6 @@ require "state_machines"
 module Phronomy
   module Agent
     class PhaseMachineBuilder
-      TOOL_EVENTS = %i[
-        tool_authorized
-        tool_approval_required
-        tool_completed
-        tool_failed
-        tool_rejected
-        tool_cancelled
-      ].freeze
-
       def initialize(entry_actions: {})
         @entry_actions = entry_actions
       end
@@ -21,26 +12,16 @@ module Phronomy
       def build
         entry_actions = @entry_actions
         callback_builder = method(:build_entry_callback)
+        condition_builder = method(:build_transition_condition)
+        external_events = InvocationTransitions::EXTERNAL_EVENTS
+        declared_states = InvocationTransitions::DECLARED_STATES
+        entry_point = InvocationTransitions::ENTRY_POINT
 
         Class.new do
           attr_accessor :context, :current_event
 
-          state_machine :phase, initial: :idle do
-            state :idle
-            state :filtering_input
-            state :building_context
-            state :calling_llm
-            state :starting_tools
-            state :evaluating_tools
-            state :waiting_for_tools
-            state :dispatching_tools
-            state :recording_tool_results
-            state :suspended
-            state :output_filtering
-            state :handed_off
-            state :completed
-            state :blocked
-            state :failed
+          state_machine :phase, initial: entry_point do
+            declared_states.each { |state_name| state state_name }
 
             event :state_completed do
               transition idle: :filtering_input
@@ -73,56 +54,17 @@ module Phronomy
                 if: ->(machine) { machine.context&.output_blocked? }
             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
-            end
-
-            event :llm_failed do
-              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|
+            external_events.each do |event_name, transitions|
               event event_name do
-                transition waiting_for_tools: :evaluating_tools
+                transitions.each do |definition|
+                  transition(
+                    definition[:from] => definition[:to],
+                    :if => condition_builder.call(definition)
+                  )
+                end
               end
             end
 
-            event :resume do
-              transition suspended: :waiting_for_tools
-            end
-
-            event :application_callback_failed do
-              transition filtering_input: :failed
-              transition building_context: :failed
-              transition calling_llm: :failed
-              transition starting_tools: :failed
-              transition evaluating_tools: :failed
-              transition waiting_for_tools: :failed
-              transition dispatching_tools: :failed
-              transition recording_tool_results: :failed
-              transition output_filtering: :failed
-            end
-
             entry_actions.each do |state_name, callables|
               callables.each do |callable|
                 after_transition(
@@ -137,6 +79,13 @@ module Phronomy
 
       private
 
+      def build_transition_condition(definition)
+        guard = definition[:guard]
+        ->(machine) {
+          guard.nil? || (!machine.context.nil? && guard.call(machine.context))
+        }
+      end
+
       def build_entry_callback(callable, state_name)
         ->(machine) {
           result = callable.call(machine.context)

data/lib/phronomy/agent/{provider_call_outcome.rb → execution/provider_call_outcome.rb}

@@ -20,7 +20,7 @@ module Phronomy
           {}
         end
         metadata = {}
-        metadata["model_id"] = message.model_id.to_s if message.respond_to?(:model_id) && message.model_id
+        metadata["model_id"] = message.model.to_s if message.respond_to?(:model) && message.model
 
         new(
           role: message.respond_to?(:role) ? message.role : :assistant,
@@ -72,15 +72,15 @@ module Phronomy
       def initialize(role:, content:, tool_calls:, usage: {}, metadata: {})
         super(
           role: role&.to_sym,
-          content: Immutable.copy(content),
-          tool_calls: Immutable.copy(Array(tool_calls)),
-          usage: Immutable.copy(usage || {}),
-          metadata: Immutable.copy(metadata || {})
+          content: Phronomy::Values::Immutable.copy(content),
+          tool_calls: Phronomy::Values::Immutable.copy(Array(tool_calls)),
+          usage: Phronomy::Values::Immutable.copy(usage || {}),
+          metadata: Phronomy::Values::Immutable.copy(metadata || {})
         )
-        Immutable.validate_canonical_json!(content, label: "Provider assistant content")
-        Immutable.validate_canonical_json!(tool_calls, label: "Provider Tool Calls")
-        Immutable.validate_canonical_json!(usage, label: "Provider usage")
-        Immutable.validate_canonical_json!(metadata, label: "Provider outcome metadata")
+        Phronomy::Values::Immutable.validate_canonical_json!(content, label: "Provider assistant content")
+        Phronomy::Values::Immutable.validate_canonical_json!(tool_calls, label: "Provider Tool Calls")
+        Phronomy::Values::Immutable.validate_canonical_json!(usage, label: "Provider usage")
+        Phronomy::Values::Immutable.validate_canonical_json!(metadata, label: "Provider outcome metadata")
         freeze
       end