phronomy 0.26.0 → 0.27.0

data/lib/phronomy/agent/persistence/queries.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    module Persistence
+      # Read and assemble domain results; the public entry point owns the execution-thread guard.
+      # @api private
+      class Queries
+        def initialize(repositories)
+          @repositories = repositories
+        end
+
+        def execution_result(execution_id)
+          execution = @repositories.executions.load(execution_id)
+          {
+            execution_id: execution.execution_id, agent_id: execution.agent_id,
+            status: execution.status, phase: execution.phase,
+            result_ref: execution.result_ref, error_ref: execution.error_ref,
+            result: execution.result_ref && @repositories.contents.fetch_text(execution.result_ref),
+            error: execution.error_ref && @repositories.contents.fetch_json(execution.error_ref)
+          }.then { |value| Phronomy::Values::Immutable.copy(value) }
+        end
+
+        def handoff_result(execution_id, main_agent_id: nil)
+          anchor = main_agent_id&.to_s
+          seen = {}
+          current = execution_id.to_s
+          reserved_agent_id = nil
+          loop do
+            raise Phronomy::Storage::SerializationError, "Cyclic durable Handoff chain" if seen[current]
+            seen[current] = true
+            begin
+              execution = @repositories.executions.load(current)
+            rescue Phronomy::Storage::NotFoundError
+              routing = @repositories.handoff_states.load(anchor)
+              if routing && Array(routing.metadata["cancelled_execution_ids"]).include?(current)
+                return {execution_id: current, agent_id: reserved_agent_id, status: :cancelled, result: nil, error: nil}.freeze
+              end
+              if reserved_agent_id && routing && routing.phase != "stable" && routing.pending_target_execution_id == current
+                return {execution_id: current, agent_id: reserved_agent_id, status: :active,
+                        phase: :target_pending, reserved: true, result: nil, error: nil}.freeze
+              end
+              raise
+            end
+            anchor ||= execution.metadata.dig("coordination", "main_agent_id")
+            unless anchor && execution.metadata.dig("coordination", "main_agent_id") == anchor
+              raise Phronomy::Storage::ConflictError, "Execution does not belong to this Handoff anchor"
+            end
+            return @repositories.execution_result(current) unless execution.status == :handed_off
+            reserved_agent_id = execution.metadata.fetch("handoff_target_agent_id")
+            current = execution.metadata.fetch("handoff_target_execution_id")
+          end
+        end
+
+        def list_executions(agent_id, after: nil, limit: 100)
+          @repositories.executions.list(agent_id, after: after, limit: limit)
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/agent/persistence/storage_schema.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    module Persistence
+      # Domain-owned metadata; storage never interprets the record payload.
+      # @api private
+      module StorageSchema
+        ROOTS = Phronomy::Storage::Resource.new(id: "agent.roots", kind: :records,
+          guard: {resource: "agent.roots", via: :key})
+        EXECUTIONS = Phronomy::Storage::Resource.new(id: "agent.executions", kind: :records,
+          attributes: {owner: :string, active: :boolean}, immutable_attributes: [:owner],
+          indexes: {owner: [:owner], owner_active: [:owner, :active]},
+          unique: [{name: :one_active_owner, fields: [:owner], where: {active: true}}],
+          guard: {resource: ROOTS.id, via: :owner})
+
+        JOURNAL = Phronomy::Storage::Resource.new(id: "agent.journal", kind: :streams,
+          guard: {resource: ROOTS.id, via: :stream})
+        HANDOFF_STATES = Phronomy::Storage::Resource.new(id: "handoff.states", kind: :records,
+          attributes: {active_agent_id: :string})
+      end
+    end
+  end
+end

data/lib/phronomy/agent/persistence/watermark.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    module Persistence
+      # Agent revision and journal position form one guarded domain watermark.
+      # @api private
+      class Watermark
+        def initialize(view) = @view = view
+
+        def check!(agent_id:, agent_revision:, journal_position:)
+          key = agent_id.to_s
+          @view.check!(guards: [Phronomy::Storage::GuardRef.new(resource: StorageSchema::ROOTS, key: key)],
+            conditions: [
+              Phronomy::Storage::Condition::RevisionIs.new(resource: StorageSchema::ROOTS,
+                key: key, expected: Integer(agent_revision)),
+              Phronomy::Storage::Condition::StreamHeadIs.new(resource: StorageSchema::JOURNAL,
+                stream: key, expected: Integer(journal_position))
+            ])
+        rescue Phronomy::Storage::ConditionFailedError => error
+          label = error.condition.is_a?(Phronomy::Storage::Condition::RevisionIs) ? "agent revision" : "journal position"
+          raise Phronomy::Storage::ConflictError, "#{label} conflict"
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/agent/recovery/invocation_restorer.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    # Reconstructs operation-local live objects from already materialized facts.
+    # Persistence reads stay with SavedContextReader and the recovery preparer.
+    # @api private
+    module InvocationRestorer
+      module_function
+
+      def build_invocation_for_suspended(agent, execution, projection, main_coordinator, listener, assistant_message:)
+        request = execution.approval_request && Phronomy::Agent::ToolApprovalRequest.from_h(
+          execution.approval_request
+        )
+        assistant_record = SavedContextReader.latest_assistant_record(execution)
+        unless assistant_record
+          raise Phronomy::ExecutionRehydrationRequiredError,
+            "suspended execution #{execution.execution_id} has no durable assistant Tool Call message"
+        end
+
+        invocation, chat, config = prepare_invocation(agent, execution, projection, main_coordinator, listener)
+        chat.messages << assistant_message
+
+        invocation.chat = chat
+        invocation.user_message_sent = true
+        invocation.approval_request = request
+        invocation.instance_variable_set(
+          :@tool_batch_llm_call_id,
+          assistant_record.llm_call_id&.to_s
+        )
+
+        by_id = (request ? request.items : []).to_h do |item|
+          [item.tool_invocation_id.to_s, item]
+        end
+        snapshots = Array(execution.metadata[ExecutionMetadata::TOOL_BATCH_METADATA_KEY])
+        if snapshots.empty?
+          raise Phronomy::ExecutionRehydrationRequiredError,
+            "suspended execution #{execution.execution_id} predates the durable Tool batch snapshot"
+        end
+
+        calls_by_id = if assistant_message.tool_calls.respond_to?(:values)
+          assistant_message.tool_calls.values.to_h do |call|
+            [call.id.to_s, call]
+          end
+        else
+          Array(assistant_message.tool_calls).to_h do |call|
+            [call.id.to_s, call]
+          end
+        end
+
+        children = snapshots.map do |snapshot|
+          entry = snapshot.to_h { |key, value| [key.to_s, value] }
+          call = calls_by_id.fetch(entry.fetch("tool_call_id").to_s) do
+            raise Phronomy::ExecutionRehydrationRequiredError,
+              "Tool Call #{entry.fetch("tool_call_id")} is missing from the durable assistant message"
+          end
+          tool = chat.tools[entry.fetch("tool_name").to_sym]
+          child = if tool
+            Phronomy::Agent::ToolInvocation.new(
+              execution_id: execution.execution_id,
+              agent: agent,
+              tool: tool,
+              tool_call: call,
+              config: config,
+              id: entry.fetch("tool_invocation_id")
+            )
+          else
+            Phronomy::Agent::ToolInvocation.missing(
+              execution_id: execution.execution_id,
+              agent: agent,
+              tool_call: call,
+              config: config,
+              id: entry.fetch("tool_invocation_id")
+            )
+          end
+          child.restore_state!(
+            status: entry.fetch("status").to_sym,
+            result: entry["result"],
+            approval_item: by_id[child.id.to_s]
+          )
+        end
+        invocation.tool_invocations = children
+        invocation
+      end
+
+      def build_chat_for_recovery(agent, execution, projection, main_coordinator, listener, messages:)
+        invocation, chat = prepare_invocation(agent, execution, projection, main_coordinator, listener)
+
+        messages.each { |message| chat.messages << message }
+
+        invocation.chat = chat
+        invocation.user_message_sent = true
+        invocation
+      end
+
+      def prepare_invocation(agent, execution, projection, main_coordinator, listener)
+        config = {
+          execution_id: execution.execution_id,
+          phronomy_execution_coordinator: main_coordinator,
+          phronomy_runtime_projection: projection
+        }.merge(agent.__coordination_config)
+        config = agent.__invocation_config(config)
+        if execution.metadata["coordination_cancel_requested"]
+          config = config.merge(cancellation_token: Phronomy::Concurrency::CancellationToken.new.cancel!)
+        end
+        invocation = Phronomy::Agent::AgentInvocation.new(
+          agent: agent,
+          input: projection.ask_message,
+          config: config,
+          event_listener: listener,
+          mode: (execution.metadata[ExecutionMetadata::INVOCATION_MODE_KEY] || "invoke").to_sym,
+          execution_id: execution.execution_id
+        )
+        chat = agent.send(:build_chat, model_config: projection.model_config)
+        agent.send(
+          :_apply_runtime_projection_to_chat,
+          chat,
+          projection,
+          invocation: invocation
+        )
+        if projection.ask_message
+          chat.messages << RubyLLM::Message.new(
+            role: :user,
+            content: projection.ask_message
+          )
+        end
+        [invocation, chat, config]
+      end
+      private_class_method :prepare_invocation
+    end
+  end
+end

data/lib/phronomy/agent/{recovery_coordinator → recovery/recovery_coordinator}/continuation.rb

@@ -33,13 +33,13 @@ module Phronomy
           return if !suspended && %i[resolution_required failed_terminal].include?(action)
 
           unless projection
-            _manifest, projection = RecoverySupport.materialize_projection(agent, execution.metadata.fetch("manifest_ref"))
+            _manifest, projection = SavedContextReader.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
+          output, usage = SavedContextReader.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
@@ -48,7 +48,7 @@ module Phronomy
           event_loop = @runtime.event_loop
           action = recovery_action(execution)
           if action == :resolution_required
-            event_loop.mark_agent_execution_admission(agent.agent_id,
+            Phronomy::Agent::ExecutionRegistry.for(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,
@@ -59,16 +59,16 @@ module Phronomy
 
           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
+          projection = Phronomy::Agent::ExecutionRegistry.for(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,
+              InvocationRestorer.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,
+              InvocationRestorer.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
@@ -77,36 +77,25 @@ module Phronomy
             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") ||
+          error = if action == :failed_terminal
+            failure = execution.metadata.dig(ExecutionMetadata::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)
+            RecoverySupport.error_from_failure(failure)
           end
+          main.deliver_on_event_loop(ExecutionCoordinator::ContinueRecoveredCommand.new(
+            coordinator: main,
+            execution_id: execution.execution_id,
+            expected_execution_revision: execution.execution_revision,
+            continuation: action,
+            invocation: invocation,
+            runtime_projection: projection,
+            result_task: completion,
+            error: error
+          ))
         end
 
         def prepare_saved_provider_calls(execution, invocation, message)
-          record = RecoverySupport.latest_assistant_record(execution)
+          record = SavedContextReader.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?
@@ -119,23 +108,10 @@ module Phronomy
           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,
+            mode: (execution.metadata[ExecutionMetadata::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::TaskResult.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,

data/lib/phronomy/agent/{recovery_coordinator → recovery/recovery_coordinator}/installation.rb

@@ -11,7 +11,7 @@ module Phronomy
         def framework_batch?(execution)
           return false unless %i[dispatching_tools resuming recovery_tools].include?(execution.phase.to_sym)
           return false if execution.status == :suspended
-          entries = Array(execution.metadata[RecoverySupport::TOOL_BATCH_METADATA_KEY])
+          entries = Array(execution.metadata[ExecutionMetadata::TOOL_BATCH_METADATA_KEY])
           pending = entries.reject { |entry| %w[completed rejected failed cancelled].include?(entry.fetch("status")) }
           !pending.empty? && pending.all? do |entry|
             entry.fetch("status") == "authorized" && agent.__framework_tool_replayable?(entry.fetch("tool_name"))
@@ -23,13 +23,13 @@ module Phronomy
         # slots then resume through their normal Tool sessions.
         def coordination_recovery_descriptor(execution)
           metadata = execution.metadata.dup
-          if metadata[RecoverySupport::TOOL_BATCH_METADATA_KEY]
-            metadata[RecoverySupport::TOOL_BATCH_METADATA_KEY] = metadata[RecoverySupport::TOOL_BATCH_METADATA_KEY].sort_by do |entry|
+          if metadata[ExecutionMetadata::TOOL_BATCH_METADATA_KEY]
+            metadata[ExecutionMetadata::TOOL_BATCH_METADATA_KEY] = metadata[ExecutionMetadata::TOOL_BATCH_METADATA_KEY].sort_by do |entry|
               agent.__framework_tool_replayable?(entry.fetch("tool_name")) ? 1 : 0
             end
           end
-          if (recovery = metadata[RecoverySupport::RECOVERY_METADATA_KEY]) && recovery["subjects"]
-            metadata[RecoverySupport::RECOVERY_METADATA_KEY] = recovery.merge("subjects" => recovery["subjects"].sort_by do |entry|
+          if (recovery = metadata[ExecutionMetadata::RECOVERY_METADATA_KEY]) && recovery["subjects"]
+            metadata[ExecutionMetadata::RECOVERY_METADATA_KEY] = recovery.merge("subjects" => recovery["subjects"].sort_by do |entry|
               agent.__framework_tool_replayable?(entry.fetch("tool_name")) ? 1 : 0
             end)
           end
@@ -45,14 +45,14 @@ module Phronomy
           manifest = base_manifest = projection = nil
           if manifest_ref
             manifest, projection =
-              RecoverySupport.materialize_projection(
+              SavedContextReader.materialize_projection(
                 agent,
                 manifest_ref
               )
             base_manifest = if base_ref.to_s == manifest_ref.to_s
               manifest
             else
-              RecoverySupport.manifest_from_ref(agent, base_ref)
+              SavedContextReader.manifest_from_ref(agent, base_ref)
             end
           end
 
@@ -151,12 +151,12 @@ module Phronomy
           bound = false
           installed = false
 
-          event_loop.admit_agent_execution(
+          Phronomy::Agent::ExecutionRegistry.for(event_loop).admit_agent_execution(
             agent.agent_id,
             owner_token: command.owner_token
           )
           admitted = true
-          event_loop.bind_agent_execution_admission(
+          Phronomy::Agent::ExecutionRegistry.for(event_loop).bind_agent_execution_admission(
             agent.agent_id,
             owner_token: command.owner_token,
             execution_id: execution.execution_id
@@ -165,13 +165,13 @@ module Phronomy
 
           invocation = nil
           if execution.status == :suspended || execution.phase.to_sym == :resuming
-            invocation = RecoverySupport.build_invocation_for_suspended(
+            invocation = InvocationRestorer.build_invocation_for_suspended(
               agent, execution, plan.projection, main, agent.send(:_phronomy_event_listener),
               assistant_message: plan.material.assistant_message
             )
           end
 
-          event_loop.install_agent_execution(
+          Phronomy::Agent::ExecutionRegistry.for(event_loop).install_agent_execution(
             execution_id: execution.execution_id,
             agent: agent,
             coordinator: main,
@@ -184,7 +184,7 @@ module Phronomy
           installed = true
 
           if execution.status == :suspended
-            event_loop.mark_agent_execution_admission(
+            Phronomy::Agent::ExecutionRegistry.for(event_loop).mark_agent_execution_admission(
               agent.agent_id,
               execution_id: execution.execution_id,
               state: :suspended
@@ -215,7 +215,7 @@ module Phronomy
 
           case plan.classification.disposition
           when Phronomy::Recovery::RESOLUTION_REQUIRED
-            event_loop.mark_agent_execution_admission(
+            Phronomy::Agent::ExecutionRegistry.for(event_loop).mark_agent_execution_admission(
               agent.agent_id,
               execution_id: execution.execution_id,
               state: :recovery_required
@@ -260,7 +260,7 @@ module Phronomy
           # simplecov:disable
           if installed
             begin
-              event_loop.release_agent_execution(
+              Phronomy::Agent::ExecutionRegistry.for(event_loop).release_agent_execution(
               execution.execution_id
             )
             rescue
@@ -270,7 +270,7 @@ module Phronomy
           if admitted
             if bound
               begin
-                event_loop.release_agent_execution_admission(
+                Phronomy::Agent::ExecutionRegistry.for(event_loop).release_agent_execution_admission(
                   agent.agent_id,
                   execution_id: execution&.execution_id
                 )
@@ -279,7 +279,7 @@ module Phronomy
               end
             else
               begin
-                event_loop.release_agent_execution_admission(
+                Phronomy::Agent::ExecutionRegistry.for(event_loop).release_agent_execution_admission(
                   agent.agent_id,
                   owner_token: command.owner_token
                 )
@@ -300,7 +300,7 @@ module Phronomy
             execution_id: execution.execution_id,
             mode: (
               execution.metadata[
-                RecoverySupport::INVOCATION_MODE_KEY
+                ExecutionMetadata::INVOCATION_MODE_KEY
               ] || "invoke"
             ).to_sym
           )
@@ -327,17 +327,13 @@ module Phronomy
               name: "agent-recovery-auto:#{execution.execution_id}"
             )
             observe_recovery_execution(internal_task, execution)
-            event_loop.mark_agent_execution_admission(
-              agent.agent_id,
+            main.deliver_on_event_loop(ExecutionCoordinator::RecoverPreparationCommand.new(
+              coordinator: main,
               execution_id: execution.execution_id,
-              state: :executing
-            )
-            main.send(
-              :start_initial_preparation_recovery_on_event_loop,
-              execution,
-              internal_task,
+              expected_execution_revision: execution.execution_revision,
+              result_task: internal_task,
               load_completion: completion
-            )
+            ))
           when :resuming
             approved = execution.approval_request &&
               (
@@ -352,18 +348,17 @@ module Phronomy
               name: "agent-recovery-auto:#{execution.execution_id}"
             )
             observe_recovery_execution(internal_task, execution)
-            event_loop.mark_agent_execution_admission(
-              agent.agent_id,
+            state = ExecutionRegistry.for(event_loop).agent_execution_state(execution.execution_id)
+            main.deliver_on_event_loop(ExecutionCoordinator::ContinueRecoveredCommand.new(
+              coordinator: main,
               execution_id: execution.execution_id,
-              state: :executing
-            )
-            main.send(
-              :start_resume_on_event_loop,
-              execution.execution_id,
-              internal_task,
-              approved: false,
-              config: {}
-            )
+              expected_execution_revision: execution.execution_revision,
+              continuation: :approval_rejection,
+              invocation: state.invocation,
+              runtime_projection: state.runtime_projection,
+              result_task: internal_task,
+              error: nil
+            ))
             completion.complete(agent)
           when :recovery_tools_completed, :recovery_provider_completed, :recovery_resolved_failed
             internal_task = Phronomy::TaskResult.deferred(name: "agent-recovery-auto:#{execution.execution_id}")