phronomy 0.25.0 → 0.27.0

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

@@ -0,0 +1,305 @@
+# frozen_string_literal: true
+
+require_relative "../../engine/concurrency/worker_input_restricted"
+
+module Phronomy
+  module Agent
+    # Commits the operation-specific prerequisites for Provider/Tool dispatch.
+    # The Agent supplies existing context/hook services, never live-state writes.
+    # Inputs and results belong to this worker boundary; delivery stays with the
+    # execution owner. No operation-local state is retained between calls.
+    # @api private
+    class DispatchPreparation
+      include Phronomy::Concurrency::WorkerInputRestricted
+
+      ProviderCommand = Data.define(
+        :execution_id, :fsm_session_id, :expected_execution_revision,
+        :root, :journal_records, :execution, :base_manifest,
+        :invocation_config, :runtime_snapshot, :streaming,
+        :pending_llm_call_id, :pending_llm_started_at
+      )
+      ToolCommand = Data.define(
+        :execution_id, :fsm_session_id, :expected_execution_revision,
+        :root, :execution, :runtime_snapshot, :tool_batch_snapshot
+      )
+      ProviderReconciliationCommand = Data.define(
+        :operation, :intended_result, :original_error
+      )
+      ToolReconciliationCommand = Data.define(
+        :operation, :intended_result, :original_error
+      )
+      ProviderResult = Data.define(:execution, :runtime_projection, :error)
+      ToolResult = Data.define(:execution)
+      ProviderReconciliationResult = Data.define(:disposition, :preparation_result)
+      ToolReconciliationResult = Data.define(:disposition, :preparation_result)
+
+      # A failed response does not prove that the execution save rolled back.
+      # @api private
+      class OutcomeUnknownError < Phronomy::Error
+        attr_reader :original_error, :intended_result
+
+        def initialize(original_error, intended_result)
+          @original_error = original_error
+          @intended_result = intended_result
+          super(
+            "durable dispatch preparation outcome is uncertain: " \
+              "#{original_error.class}: #{original_error.message}"
+          )
+          set_backtrace(original_error.backtrace)
+        end
+      end
+
+      # @api private
+      def initialize(agent:, persistence:)
+        @agent = agent
+        @persistence = persistence
+      end
+
+      # @api private
+      def prepare_provider(operation)
+        staged = stage_provider_call(operation)
+        recorded = encode_provider_records(operation, staged)
+        assembler, prepared = prepare_provider_context(operation, recorded)
+        committed, manifest, manifest_ref = commit_provider_preparation(
+          operation, recorded, assembler, prepared
+        )
+        materialize_provider_result(committed.execution, manifest, manifest_ref)
+      end
+
+      # @api private
+      def prepare_tools(operation)
+        intended = nil
+        begin
+          @persistence.transaction do |tx|
+            assert_local_durable_base!(tx, operation.root)
+            updated = build_tool_dispatch_execution(operation, tx)
+            updated = @agent.__prepare_coordination_record(updated, tx: tx)
+            tx.executions.save(
+              operation.execution.execution_id,
+              expected_revision: operation.execution.execution_revision,
+              execution: updated
+            )
+            intended = ToolResult.new(execution: updated)
+          end
+        rescue => caught
+          raise if known_durable_failure?(caught) || intended.nil?
+
+          raise OutcomeUnknownError.new(caught, intended)
+        end
+        intended
+      end
+
+      # @api private
+      def reconcile_provider(command)
+        disposition, current = reconcile_preparation(
+          command.operation, command.intended_result.execution
+        )
+        result = restore_provider_result(current) if disposition == :committed
+        ProviderReconciliationResult.new(
+          disposition: disposition, preparation_result: result
+        )
+      end
+
+      # @api private
+      def reconcile_tools(command)
+        disposition, current = reconcile_preparation(
+          command.operation, command.intended_result.execution
+        )
+        result = ToolResult.new(execution: current) if disposition == :committed
+        ToolReconciliationResult.new(
+          disposition: disposition, preparation_result: result
+        )
+      end
+
+      private
+
+      def stage_provider_call(operation)
+        metadata = operation.execution.metadata.dup
+        metadata.delete(ExecutionMetadata::TOOL_BATCH_METADATA_KEY)
+        metadata.delete(ExecutionMetadata::RECOVERY_METADATA_KEY)
+        metadata[ExecutionMetadata::PENDING_LLM_ID_KEY] = operation.pending_llm_call_id
+        metadata[ExecutionMetadata::PENDING_LLM_STARTED_AT_KEY] = operation.pending_llm_started_at
+        metadata[ExecutionMetadata::CONTRACT_VERSION_KEY] = ExecutionMetadata::CONTRACT_VERSION
+        operation.execution.with(
+          execution_revision: operation.execution.execution_revision,
+          metadata: metadata
+        )
+      end
+
+      def encode_provider_records(operation, staged)
+        encoded_records = call_records = nil
+        # Content-addressed records may be added here; Execution is not advanced.
+        @persistence.transaction do |tx|
+          assert_local_durable_base!(tx, operation.root)
+          encoded_records, call_records = RuntimeRecordEncoder.encode(
+            staged,
+            agent_id: @agent.agent_id,
+            tx: tx,
+            snapshot: operation.runtime_snapshot,
+            context_candidate: true,
+            agent_root: operation.root
+          )
+        end
+        staged.with(
+          execution_revision: staged.execution_revision,
+          phase: :preparing_llm_call,
+          working_records: staged.working_records + encoded_records,
+          llm_calls: staged.llm_calls + call_records
+        )
+      end
+
+      def prepare_provider_context(operation, recorded)
+        patch = @agent.send(
+          :run_before_llm_input_hooks,
+          call_sequence: recorded.llm_calls.length + 1,
+          config: operation.invocation_config
+        )
+        assembler = ContextAssembler.new(
+          agent: @agent,
+          persistence: @persistence,
+          journal_records: operation.journal_records
+        )
+        prepared = assembler.prepare_followup(
+          base_manifest: operation.base_manifest,
+          agent_root: operation.root,
+          execution: recorded,
+          config: operation.invocation_config,
+          patch: patch
+        )
+        @agent.send(
+          :check_cancellation!,
+          operation.invocation_config,
+          "invocation cancelled after context policy"
+        )
+        [assembler, prepared]
+      end
+
+      def commit_provider_preparation(operation, recorded, assembler, prepared)
+        manifest = manifest_ref = intended = nil
+        begin
+          @persistence.transaction do |tx|
+            assert_local_durable_base!(tx, operation.root)
+            manifest, manifest_ref = assembler.finalize(prepared, persistence: tx)
+            updated = execution_with_provider_manifest(recorded, manifest_ref)
+            updated = @agent.__prepare_coordination_record(updated, tx: tx)
+            tx.executions.save(
+              operation.execution.execution_id,
+              expected_revision: operation.execution.execution_revision,
+              execution: updated
+            )
+            intended = ProviderResult.new(
+              execution: updated, runtime_projection: nil, error: nil
+            )
+          end
+        rescue => caught
+          raise if known_durable_failure?(caught) || intended.nil?
+
+          raise OutcomeUnknownError.new(caught, intended)
+        end
+        [intended, manifest, manifest_ref]
+      end
+
+      def execution_with_provider_manifest(recorded, manifest_ref)
+        refs = Array(recorded.metadata["manifest_refs"]) + [manifest_ref]
+        recorded.with(
+          phase: :calling_llm,
+          metadata: recorded.metadata.merge(
+            "manifest_ref" => manifest_ref,
+            "manifest_refs" => refs
+          )
+        )
+      end
+
+      def materialize_provider_result(execution, manifest, manifest_ref)
+        projection = materialization_error = nil
+        begin
+          projection = RubyLLMMaterializer.new(
+            agent: @agent, persistence: @persistence
+          ).materialize(manifest: manifest, manifest_ref: manifest_ref)
+        rescue => error
+          materialization_error = error
+        end
+        ProviderResult.new(
+          execution: execution, runtime_projection: projection,
+          error: materialization_error
+        )
+      end
+
+      def restore_provider_result(execution)
+        projection = materialization_error = nil
+        begin
+          _manifest, projection = SavedContextReader.materialize_projection(
+            @agent, execution.metadata.fetch("manifest_ref")
+          )
+        rescue => error
+          materialization_error = error
+        end
+        ProviderResult.new(
+          execution: execution, runtime_projection: projection,
+          error: materialization_error
+        )
+      end
+
+      def build_tool_dispatch_execution(operation, tx)
+        encoded_records, call_records = RuntimeRecordEncoder.encode(
+          operation.execution,
+          agent_id: @agent.agent_id,
+          tx: tx,
+          snapshot: operation.runtime_snapshot,
+          context_candidate: true,
+          agent_root: operation.root
+        )
+        operation.execution.with(
+          phase: :dispatching_tools,
+          working_records: operation.execution.working_records + encoded_records,
+          llm_calls: operation.execution.llm_calls + call_records,
+          metadata: tool_dispatch_metadata(operation)
+        )
+      end
+
+      def tool_dispatch_metadata(operation)
+        metadata = operation.execution.metadata.dup
+        metadata.delete(ExecutionMetadata::PENDING_LLM_ID_KEY)
+        metadata.delete(ExecutionMetadata::PENDING_LLM_STARTED_AT_KEY)
+        metadata.delete(ExecutionMetadata::RECOVERY_METADATA_KEY)
+        metadata.delete("framework_calls_pending")
+        metadata[ExecutionMetadata::TOOL_BATCH_METADATA_KEY] =
+          Phronomy::Values::Serializable.convert(operation.tool_batch_snapshot,
+            unsupported_message: "Recovery value is not canonically serializable")
+        metadata[ExecutionMetadata::CONTRACT_VERSION_KEY] = ExecutionMetadata::CONTRACT_VERSION
+        metadata
+      end
+
+      def reconcile_preparation(operation, intended_execution)
+        current = @persistence.executions.load(operation.execution_id)
+        if current.execution_revision == intended_execution.execution_revision &&
+            current.to_h == intended_execution.to_h
+          return [:committed, current]
+        end
+        if current.execution_revision == operation.execution.execution_revision &&
+            current.to_h == operation.execution.to_h
+          return [:not_committed, current]
+        end
+
+        [:conflict, current]
+      end
+
+      def known_durable_failure?(error)
+        error.is_a?(Phronomy::Storage::ConflictError) ||
+          error.is_a?(Phronomy::Storage::NotFoundError) ||
+          error.is_a?(Phronomy::Storage::SerializationError) ||
+          error.is_a?(Phronomy::Storage::UnsupportedBackendError) ||
+          error.is_a?(ArgumentError) ||
+          error.is_a?(Phronomy::ConfigurationError)
+      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
+    end
+  end
+end

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

@@ -4,7 +4,7 @@ module Phronomy
   module Agent
     # Observes a reserved execution using ordinary Agent admission and Recovery.
     # Durable reads/materialization run off EventLoop. Workers never wait for a
-    # child lifecycle: the existing EventLoop completion waiter settles Task.
+    # child lifecycle: the existing EventLoop completion waiter settles TaskResult.
     # @api private
     class ExactExecution
       Wait = Data.define(:coordinator, :agent, :execution_id)
@@ -17,7 +17,7 @@ module Phronomy
       def initialize(agent, execution_id, input, config)
         @agent, @id, @input, @config = agent, execution_id.to_s.freeze, input, config.freeze
         @runtime = Phronomy::Runtime.instance
-        @completion = Phronomy::Task.deferred(name: "exact-execution:#{@id}")
+        @completion = Phronomy::TaskResult.deferred(name: "exact-execution:#{@id}")
       end
 
       def start
@@ -26,7 +26,7 @@ module Phronomy
           if execution&.terminal?
             [:terminal, materialize(execution)]
           elsif execution
-            unless @runtime.__agent_execution_owner(@id)
+            unless Phronomy::Agent::ExecutionRegistry.existing_for(@runtime)&.agent_execution_owner(@id)
               @agent.instance_variable_set(:@_phronomy_coordination_config, @config)
               begin
                 RecoveryCoordinator.new(@agent).recover_on_load!
@@ -55,8 +55,7 @@ module Phronomy
               source.on_complete { |_value, failure| reconcile(failure) }
             when :active
               command = Wait.new(coordinator: self, agent: @agent, execution_id: @id)
-              posted = @runtime.event_loop.post(Phronomy::Event.new(type: :agent_terminal_ready,
-                target_id: Phronomy::EventLoop::SYSTEM_CHANNEL_ID, payload: {command: command}))
+              posted = ExecutionRegistry.for(@runtime.event_loop).post(command, completion: @completion)
               @completion.fail(Phronomy::RuntimeShutdownError.new("Exact execution observer rejected")) unless posted
             end
           end
@@ -70,7 +69,7 @@ module Phronomy
       end
 
       def deliver_on_event_loop(command)
-        state = @runtime.event_loop.agent_execution_state(command.execution_id)
+        state = Phronomy::Agent::ExecutionRegistry.for(@runtime.event_loop).agent_execution_state(command.execution_id)
         unless state
           # Ownership can be released between the durable read and this command.
           # Reinstall once with the caller's current wiring/cancellation request.
@@ -81,7 +80,7 @@ module Phronomy
           return reconcile(nil)
         end
         unless state.agent.equal?(command.agent)
-          raise Phronomy::Persistence::ConflictError, "Exact execution #{@id} owner mismatch"
+          raise Phronomy::Storage::ConflictError, "Exact execution #{@id} owner mismatch"
         end
         if @config[:cancellation_token]&.cancelled?
           state.invocation&.config&.fetch(:cancellation_token, nil)&.cancel!
@@ -92,9 +91,9 @@ module Phronomy
         end
         observers = Array(state.invocation.config[:phronomy_exact_observers])
         state.invocation.merge_config!(phronomy_exact_observers: (observers + [@completion]).uniq.freeze)
-        waiter = Phronomy::Task.deferred(name: "exact-wait:#{@id}")
+        waiter = Phronomy::TaskResult.deferred(name: "exact-wait:#{@id}")
         waiter.on_complete { |_result, failure| reconcile(failure) }
-        @runtime.event_loop.register_agent_completion_waiter(@id, waiter)
+        Phronomy::Agent::ExecutionRegistry.for(@runtime.event_loop).register_agent_completion_waiter(@id, waiter)
       rescue => failure
         @completion.fail(failure)
       end
@@ -104,11 +103,11 @@ module Phronomy
       def read_execution
         begin
           execution = @agent.persistence.executions.load(@id)
-        rescue Phronomy::Persistence::NotFoundError
+        rescue Phronomy::Storage::NotFoundError
           return nil
         end
         unless execution.agent_id == @agent.agent_id
-          raise Phronomy::Persistence::ConflictError, "Reserved execution #{@id} belongs to another Agent"
+          raise Phronomy::Storage::ConflictError, "Reserved execution #{@id} belongs to another Agent"
         end
         expected = @config[:phronomy_coordination]
         stored = execution.metadata["coordination"]
@@ -116,12 +115,12 @@ module Phronomy
           actual_identity = stored&.except("handoff_revision")
           expected_identity = expected.except("handoff_revision")
           unless actual_identity == expected_identity
-            raise Phronomy::Persistence::ConflictError, "Reserved execution #{@id} coordination mismatch"
+            raise Phronomy::Storage::ConflictError, "Reserved execution #{@id} coordination mismatch"
           end
         end
         ref = execution.metadata["current_input_ref"]
         if ref && @agent.persistence.contents.fetch_text(ref) != @input
-          raise Phronomy::Persistence::ConflictError, "Reserved execution #{@id} input mismatch"
+          raise Phronomy::Storage::ConflictError, "Reserved execution #{@id} input mismatch"
         end
         execution
       end

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

@@ -11,12 +11,11 @@ module Phronomy
 
       def self.signal(execution_id, agent_id)
         command = Command.new(coordinator: new, execution_id: execution_id, agent_id: agent_id)
-        Phronomy::Runtime.instance.event_loop.post(Phronomy::Event.new(type: :agent_terminal_ready,
-          target_id: Phronomy::EventLoop::SYSTEM_CHANNEL_ID, payload: {command: command}))
+        ExecutionRegistry.for(Phronomy::Runtime.instance.event_loop).post(command)
       end
 
       def deliver_on_event_loop(command)
-        state = Phronomy::Runtime.instance.event_loop.agent_execution_state(command.execution_id)
+        state = Phronomy::Agent::ExecutionRegistry.for(Phronomy::Runtime.instance.event_loop).agent_execution_state(command.execution_id)
         return unless state && state.agent.agent_id == command.agent_id
         state.invocation&.config&.fetch(:cancellation_token, nil)&.cancel!
       end