phronomy 0.23.0 → 0.24.0

data/lib/phronomy/{multi_agent → agent}/handoff.rb

@@ -1,9 +1,9 @@
 # frozen_string_literal: true
 
-require "securerandom"
+require "digest"
 
 module Phronomy
-  module MultiAgent
+  module Agent
     # Application-defined semantic edge for transferring active responsibility
     # from one live Agent instance to another.
     class Handoff
@@ -19,14 +19,14 @@ module Phronomy
           raise ArgumentError, "Handoff source_agent and target_agent must be different instances"
         end
         unless policy.is_a?(HandoffPolicy)
-          raise ArgumentError, "policy must be a Phronomy::MultiAgent::HandoffPolicy"
+          raise ArgumentError, "policy must be a Phronomy::Agent::HandoffPolicy"
         end
 
         @source_agent = source_agent
         @target_agent = target_agent
         @policy = policy
         @description = (description || default_description).to_s.freeze
-        @transport_key = SecureRandom.hex(8).freeze
+        @transport_key = Digest::SHA256.hexdigest([source_agent.agent_id, target_agent.agent_id].join("\0"))[0, 32].freeze
         freeze
       end
 

data/lib/phronomy/{multi_agent → agent}/handoff_capability_factory.rb

@@ -1,13 +1,8 @@
 # frozen_string_literal: true
 
-require "weakref"
-
 module Phronomy
-  module MultiAgent
+  module Agent
     class HandoffCapabilityFactory
-      REGISTRY_MUTEX = Mutex.new
-      private_constant :REGISTRY_MUTEX
-
       Binding = Data.define(:handoff, :tool_class, :tool_name) do
         def initialize(handoff:, tool_class:, tool_name:)
           super(handoff: handoff, tool_class: tool_class, tool_name: tool_name.to_s.freeze)
@@ -17,9 +12,7 @@ module Phronomy
 
       def self.build(handoff)
         key = handoff.send(:transport_key)
-        source_name = class_slug(handoff.source_agent.class)
-        target_name = class_slug(handoff.target_agent.class)
-        tool_name = "phronomy_handoff_#{source_name}_to_#{target_name}_#{key}"
+        tool_name = "phronomy_handoff_#{key}"
         description = handoff.description
         policy = handoff.policy
 
@@ -45,43 +38,8 @@ module Phronomy
           end
         end
 
-        binding = Binding.new(handoff: handoff, tool_class: klass, tool_name: tool_name)
-        registry_mutex.synchronize { registry[tool_name] = WeakRef.new(binding) }
-        binding
-      end
-
-      def self.lookup(tool_name)
-        key = tool_name.to_s
-        registry_mutex.synchronize do
-          reference = registry[key]
-          return nil unless reference
-
-          begin
-            reference.__getobj__
-          rescue WeakRef::RefError
-            registry.delete(key)
-            nil
-          end
-        end
-      end
-
-      def self.registry
-        @registry ||= {}
-      end
-      private_class_method :registry
-
-      def self.registry_mutex
-        REGISTRY_MUTEX
-      end
-      private_class_method :registry_mutex
-
-      def self.class_slug(klass)
-        raw = (klass.name || "agent").gsub("::", "_")
-        raw.gsub(/([a-z\d])([A-Z])/, '\\1_\\2')
-          .gsub(/[^a-zA-Z0-9_]/, "_")
-          .downcase
+        Binding.new(handoff: handoff, tool_class: klass, tool_name: tool_name)
       end
-      private_class_method :class_slug
     end
   end
 end

data/lib/phronomy/{multi_agent → agent}/handoff_context.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Phronomy
-  module MultiAgent
+  module Agent
     class HandoffContext
       Provenance = Data.define(
         :origin_agent_id,
@@ -79,6 +79,31 @@ module Phronomy
         end
       end
 
+      def to_h
+        {
+          "responsibility" => responsibility,
+          "items" => items.map do |item|
+            item.to_h.transform_keys(&:to_s).merge(
+              "candidate_category" => item.candidate_category.to_s,
+              "policy_category" => item.policy_category.to_s,
+              "role" => item.role&.to_s,
+              "content_format" => item.content_format.to_s,
+              "provenance" => item.provenance.to_h
+            )
+          end
+        }.freeze
+      end
+
+      def self.from_h(value)
+        source = value.transform_keys(&:to_s)
+        raise ArgumentError, "HandoffContext schema mismatch" unless source.keys.sort == %w[items responsibility]
+        new(responsibility: source.fetch("responsibility"), items: source.fetch("items").map do |raw|
+          values = raw.transform_keys(&:to_sym)
+          values[:provenance] = Provenance.new(**values.fetch(:provenance).transform_keys(&:to_sym))
+          Item.new(**values)
+        end)
+      end
+
       attr_reader :responsibility, :items
 
       def initialize(responsibility:, items: [])

data/lib/phronomy/{multi_agent/execution_coordinator.rb → agent/handoff_execution_coordinator.rb}

@@ -1,12 +1,14 @@
 # frozen_string_literal: true
 
+require "digest"
+
 module Phronomy
-  module MultiAgent
+  module Agent
     # Handoff-aware specialization of the normal Agent execution coordinator.
     # It changes only the durable terminal semantics of an invocation that
     # produced a typed HandoffRequest. EventLoop ownership/apply remains entirely
     # in Agent::ExecutionCoordinator.
-    class ExecutionCoordinator < Phronomy::Agent::ExecutionCoordinator
+    class HandoffExecutionCoordinator < Phronomy::Agent::ExecutionCoordinator
       private
 
       def compute_terminal(operation)
@@ -17,7 +19,9 @@ module Phronomy
             view.callback_failure.to_stream_callback_error
           )
         end
-        return commit_failed_outcome(operation, view.source_error) if view.source_error
+        error = view.source_error || view.block_error || view.invocation_error
+        raise error if error.is_a?(Phronomy::ExecutionRehydrationRequiredError)
+        return commit_failed_outcome(operation, error) if error
         return commit_suspended(operation) if view.phase == :suspended
 
         raise view.block_error if view.input_blocked || view.output_blocked
@@ -27,7 +31,7 @@ module Phronomy
 
         commit_completed(operation)
       rescue => caught
-        commit_failed_outcome(operation, caught)
+        reconcile_terminal_error(operation, caught)
       end
 
       def commit_handed_off(operation)
@@ -38,6 +42,27 @@ module Phronomy
         handed_off = next_root = appended = nil
 
         @agent.persistence.transaction do |tx|
+          coordination = current.metadata.fetch("coordination")
+          main_id = coordination.fetch("main_agent_id")
+          routing = tx.handoff_states.load(main_id)
+          unless routing && routing.active_agent_id == @agent.agent_id && routing.handoff_revision == coordination.fetch("handoff_revision")
+            raise Phronomy::Persistence::ConflictError, "Handoff routing changed before Source transfer"
+          end
+          if Array(routing.metadata["cancelled_execution_ids"]).include?(current.execution_id)
+            raise Phronomy::CancellationError, "Handoff Source turn was cancelled"
+          end
+          manifest = RecoverySupport.manifest_from_ref(@agent, current.metadata.fetch("manifest_ref"))
+          context = HandoffProjection.new.build_terminal(view: request, manifest: manifest,
+            persistence: tx, source_agent_id: @agent.agent_id)
+          context_ref = tx.contents.put_json(context.to_h)
+          target_id = "handoff-target-#{Digest::SHA256.hexdigest([current.execution_id, request.target_agent_id].join("\0"))}"
+          target_root = tx.agents.load(request.target_agent_id)
+          target_definition = {"id" => target_root.agent_definition_id, "version" => target_root.agent_definition_version}
+          transfer = routing.with(active_agent_id: request.target_agent_id,
+            active_handoff_context_ref: context_ref, phase: "target_pending",
+            pending_source_execution_id: current.execution_id, pending_target_execution_id: target_id,
+            metadata: routing.metadata.merge("target_definition" => target_definition))
+          tx.handoff_states.save(main_id, expected_revision: routing.handoff_revision, state: transfer)
           encoded_records, call_records = encode_runtime_records(
             current,
             tx: tx,
@@ -79,7 +104,9 @@ module Phronomy
             working_records: [],
             llm_calls: current.llm_calls + call_records,
             approval_request: nil,
-            terminal_reason: "handed_off"
+            terminal_reason: "handed_off",
+            metadata: current.metadata.merge("handoff_target_agent_id" => request.target_agent_id,
+              "handoff_target_execution_id" => target_id, "handoff_context_ref" => context_ref)
           )
           tx.executions.save(
             current.execution_id,

data/lib/phronomy/{multi_agent → agent}/handoff_policy.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Phronomy
-  module MultiAgent
+  module Agent
     class HandoffPolicy
       CATEGORIES = %i[current_request history knowledge tool_exchanges].freeze
       MODES = %i[required forbidden selectable].freeze
@@ -77,6 +77,12 @@ module Phronomy
         builder.build
       end
 
+      # Reconstructs a value-only operation snapshot, not Application code.
+      # @api private
+      def self.from_h(value)
+        new(value.map { |category, rule| Rule.new(category: category, **rule.transform_keys(&:to_sym)) })
+      end
+
       def self.default
         @default ||= define do
           required :current_request

data/lib/phronomy/{multi_agent → agent}/handoff_projection.rb

@@ -1,13 +1,29 @@
 # frozen_string_literal: true
 
 module Phronomy
-  module MultiAgent
+  module Agent
     class HandoffProjection
       CONTROL_CATEGORIES = %i[instruction handoff_responsibility].freeze
       JSON_CATEGORIES = %i[assistant_message tool_message].freeze
 
+      Identity = Data.define(:agent_id)
+      Edge = Data.define(:policy, :target_agent)
+      Snapshot = Data.define(:handoff, :responsibility, :selection_intent)
+      private_constant :Identity, :Edge, :Snapshot
+
+      # A terminal command contains values only, captured on EventLoop.
+      def build_terminal(view:, manifest:, persistence:, source_agent_id:)
+        request = Snapshot.new(
+          handoff: Edge.new(policy: HandoffPolicy.from_h(view.policy), target_agent: Identity.new(agent_id: view.target_agent_id)),
+          responsibility: view.responsibility,
+          selection_intent: view.selection_intent.transform_keys(&:to_sym)
+        )
+        build(request: request, manifest: manifest, persistence: persistence,
+          source_agent: Identity.new(agent_id: source_agent_id))
+      end
+
       def build(request:, manifest:, persistence:, source_agent:)
-        unless request.is_a?(HandoffRequest)
+        unless request.is_a?(HandoffRequest) || request.is_a?(Snapshot)
           raise ArgumentError, "request must be a HandoffRequest"
         end
         unless manifest.is_a?(Phronomy::Agent::LLMInputManifest)

data/lib/phronomy/{multi_agent → agent}/handoff_request.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Phronomy
-  module MultiAgent
+  module Agent
     # Typed private control request produced from one intercepted Handoff capability.
     # @api private
     HandoffRequest = Data.define(
@@ -11,7 +11,7 @@ module Phronomy
         responsibility = responsibility.to_s.strip
         raise ArgumentError, "Handoff responsibility must not be empty" if responsibility.empty?
         unless handoff.is_a?(Handoff)
-          raise ArgumentError, "handoff must be a Phronomy::MultiAgent::Handoff"
+          raise ArgumentError, "handoff must be a Phronomy::Agent::Handoff"
         end
 
         normalized = handoff.policy.selectable_categories.to_h do |category|

data/lib/phronomy/agent/handoff_runner.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Phronomy
+  module Agent
+    # Durable Agent-domain responsibility routing within one Persistence instance.
+    # @api public
+    class HandoffRunner
+      MAX_HANDOFFS = 20
+
+      # @api public
+      attr_reader :main_agent, :handoffs
+
+      # @api public
+      def initialize(main_agent:, handoffs: [])
+        @main_agent, @handoffs = main_agent, Array(handoffs).freeze
+        @persistence = main_agent.persistence
+        raise ArgumentError, "handoffs must contain Agent::Handoff" unless @handoffs.all? { |h| h.is_a?(Handoff) }
+        @agents = ([main_agent] + @handoffs.flat_map { |edge| [edge.source_agent, edge.target_agent] }).uniq.to_h { |a| [a.agent_id, a] }.freeze
+        unless @agents.values.all? { |a| a.persistence.equal?(@persistence) }
+          raise Phronomy::ConfigurationError, "Durable Handoff graph requires one Persistence instance"
+        end
+        if @handoffs.group_by { |h| [h.source_agent.agent_id, h.target_agent.agent_id] }.any? { |_, edges| edges.size > 1 }
+          raise ArgumentError, "Duplicate Source/Target Handoff edges"
+        end
+        @bindings = @handoffs.group_by { |h| h.source_agent.agent_id }.transform_values { |edges| edges.map { |h| HandoffCapabilityFactory.build(h) }.freeze }.freeze
+        @runtime = Phronomy::Runtime.instance
+      end
+
+      # @api public
+      def invoke(input, config: {})
+        trace_handle = Phronomy::Tracing::Automatic.start("multi_agent.turn",
+          input: input, main_agent_id: main_agent.agent_id,
+          **main_agent.send(:_build_caller_meta, config))
+        operation_error = result = nil
+        if Phronomy::Runtime.in_event_loop_context?
+          raise Phronomy::EventLoopReentrancyError, "HandoffRunner#invoke cannot block EventLoop"
+        end
+        unless Phronomy::Runtime.instance.equal?(@runtime)
+          raise Phronomy::RuntimeShutdownError, "HandoffRunner belongs to a previous Runtime"
+        end
+        config = config.merge(cancellation_token: config[:cancellation_token] || Phronomy::Concurrency::CancellationToken.new)
+        @runtime.__admit_multi_agent(main_agent)
+        admitted = true
+        state = load_state
+        count = 0
+        loop do
+          active = @agents.fetch(state.active_agent_id) do
+            raise Phronomy::ExecutionRehydrationRequiredError, "Handoff graph lacks active Agent #{state.active_agent_id}"
+          end
+          context = state.active_handoff_context_ref && HandoffContext.from_h(@persistence.contents.fetch_json(state.active_handoff_context_ref))
+          wiring = config.merge(phronomy_handoff_bindings: @bindings.fetch(active.agent_id, []),
+            phronomy_handoff_context: context,
+            phronomy_coordination: {"kind" => "handoff", "main_agent_id" => main_agent.agent_id, "handoff_revision" => state.handoff_revision}).freeze
+          active.instance_variable_set(:@_phronomy_coordination_config, wiring)
+          result = if state.phase == "stable"
+            unfinished = @persistence.executions.list_active(active.agent_id)
+            if unfinished.empty?
+              active.invoke(input, config: wiring)
+            else
+              exact = unfinished.fetch(0)
+              unless unfinished.size == 1 && exact.metadata.dig("coordination", "main_agent_id") == main_agent.agent_id
+                raise Phronomy::Persistence::ConflictError, "Active Agent execution belongs to another coordination turn"
+              end
+              wiring[:cancellation_token].cancel! if Array(state.metadata["cancelled_execution_ids"]).include?(exact.execution_id)
+              stored_input = @persistence.contents.fetch_text(exact.metadata.fetch("current_input_ref"))
+              ExactExecution.start(agent: active, execution_id: exact.execution_id, input: stored_input, config: wiring).wait_result
+            end
+          else
+            source = @persistence.executions.load(state.pending_source_execution_id)
+            unless @handoffs.any? { |edge| edge.source_agent.agent_id == source.agent_id && edge.target_agent.agent_id == state.active_agent_id }
+              raise Phronomy::ExecutionRehydrationRequiredError, "Handoff graph lacks committed Source/Target edge"
+            end
+            definition = state.metadata.fetch("target_definition")
+            unless active.class.agent_definition == definition.transform_keys(&:to_sym)
+              raise Phronomy::ConfigurationError, "Handoff Target definition mismatch"
+            end
+            wiring[:cancellation_token].cancel! if Array(state.metadata["cancelled_execution_ids"]).include?(state.pending_target_execution_id)
+            ExactExecution.start(agent: active, execution_id: state.pending_target_execution_id,
+              input: context.responsibility, config: wiring).wait_result
+          end
+          execution = @persistence.executions.load(result.fetch(:execution_id))
+          if execution.status == :handed_off
+            count += 1
+            raise Phronomy::HandoffError, "Exceeded maximum Handoffs in one turn" if count > MAX_HANDOFFS
+            state = @persistence.handoff_states.load(main_agent.agent_id)
+            next
+          end
+          if execution.active?
+            raise Phronomy::ExecutionRehydrationRequiredError, "Handoff execution requires approval or recovery"
+          end
+          raise RecoverySupport.error_from_failure(result[:error]) if result[:error]
+          return result.reject { |key, _| key.to_s.start_with?("_phronomy_") || key == :handoff_request }.merge(agent: active)
+        end
+      rescue Phronomy::CancellationError => error
+        operation_error = error
+        cancel(state.pending_source_execution_id) if state && state.phase != "stable"
+        raise
+      rescue => error
+        operation_error = error
+        raise
+      ensure
+        @runtime.__release_multi_agent(main_agent) if admitted
+        Phronomy::Tracing::Automatic.finish(trace_handle, output: result && result[:output], error: operation_error)
+      end
+
+      # Durably scopes cancellation to an exact turn, including a transferred
+      # Target reservation. A completed older turn never cancels a later turn.
+      # @api public
+      def cancel(execution_id)
+        if Phronomy::Runtime.in_event_loop_context?
+          raise Phronomy::EventLoopReentrancyError, "HandoffRunner#cancel cannot block EventLoop"
+        end
+        intended = leaf = leaf_id = nil
+        begin
+          @persistence.transaction do |tx|
+            first = tx.executions.load(execution_id)
+            unless first.metadata.dig("coordination", "main_agent_id") == main_agent.agent_id
+              raise Phronomy::Persistence::ConflictError, "Execution does not belong to this Handoff anchor"
+            end
+            leaf = first
+            leaf_id = first.execution_id
+            seen = {}
+            while leaf&.status == :handed_off
+              raise Phronomy::Persistence::SerializationError, "Cyclic Handoff chain" if seen[leaf_id]
+              seen[leaf_id] = true
+              leaf_id = leaf.metadata.fetch("handoff_target_execution_id")
+              begin
+                leaf = tx.executions.load(leaf_id)
+              rescue Phronomy::Persistence::NotFoundError
+                leaf = nil
+              end
+            end
+            next if leaf&.terminal?
+            routing = tx.handoff_states.load(main_agent.agent_id)
+            unless routing && (leaf ? routing.active_agent_id == leaf.agent_id : routing.pending_target_execution_id == leaf_id)
+              raise Phronomy::Persistence::ConflictError, "Handoff routing no longer owns the requested turn"
+            end
+            ids = (Array(routing.metadata["cancelled_execution_ids"]) + [leaf_id]).uniq
+            intended = routing.with(phase: leaf ? routing.phase : "stable",
+              metadata: routing.metadata.merge("cancelled_execution_ids" => ids))
+            tx.handoff_states.save(main_agent.agent_id, expected_revision: routing.handoff_revision, state: intended)
+          end
+        rescue => error
+          confirmed = @persistence.handoff_states.load(main_agent.agent_id)
+          raise error unless intended && confirmed && Array(confirmed.metadata["cancelled_execution_ids"]).include?(leaf_id)
+        end
+        return @persistence.execution_result(leaf_id) if leaf&.terminal?
+        ExecutionCancellation.signal(leaf_id, leaf.agent_id) if leaf&.active?
+        {execution_id: leaf_id, cancellation_requested: !leaf&.terminal?}.freeze
+      end
+
+      # Reads a specified source/Target chain without current graph continuation.
+      # @api public
+      def result(execution_id)
+        @persistence.handoff_result(execution_id, main_agent_id: main_agent.agent_id)
+      end
+
+      private
+
+      def load_state
+        state = @persistence.handoff_states.load(main_agent.agent_id)
+        return state if state
+        now = Time.now.utc.iso8601(6)
+        initial = HandoffState.new(main_agent_id: main_agent.agent_id, handoff_revision: 1,
+          active_agent_id: main_agent.agent_id, active_handoff_context_ref: nil,
+          phase: "stable", pending_source_execution_id: nil, pending_target_execution_id: nil,
+          created_at: now, updated_at: now, metadata: {})
+        @persistence.transaction { |tx| tx.handoff_states.save(main_agent.agent_id, expected_revision: nil, state: initial) }
+      rescue => error
+        confirmed = @persistence.handoff_states.load(main_agent.agent_id)
+        raise error unless confirmed
+        confirmed
+      end
+    end
+  end
+end

data/lib/phronomy/agent/handoff_state.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Phronomy
+  module Agent
+    # Immutable current-format semantic record; contains no Runtime handles.
+    # @api private
+    class HandoffState
+      ATTRIBUTES = %w[main_agent_id handoff_revision active_agent_id active_handoff_context_ref phase pending_source_execution_id pending_target_execution_id created_at updated_at metadata].freeze
+      attr_reader(*ATTRIBUTES)
+
+      def initialize(**values)
+        source = values.transform_keys(&:to_s)
+        raise ArgumentError, "HandoffState schema mismatch" unless source.keys.sort == ATTRIBUTES.sort
+        canonical = Phronomy::CanonicalJSON.load(Phronomy::CanonicalJSON.dump(source))
+        ATTRIBUTES.each { |key| instance_variable_set("@#{key}", Phronomy::Agent::Immutable.copy(canonical.fetch(key))) }
+        raise ArgumentError, "missing main_agent_id" if main_agent_id.to_s.empty?
+        raise ArgumentError, "invalid handoff_revision" unless handoff_revision.is_a?(Integer) && handoff_revision >= 0
+        raise ArgumentError, "invalid metadata" unless metadata.is_a?(Hash)
+        raise ArgumentError, "invalid Handoff phase" unless %w[stable target_pending target_active].include?(phase)
+        raise ArgumentError, "missing active Agent" if active_agent_id.to_s.empty?
+        if phase != "stable" && pending_target_execution_id.to_s.empty?
+          raise ArgumentError, "pending Handoff requires exact Target execution"
+        end
+        freeze
+      end
+
+      def to_h = ATTRIBUTES.to_h { |key| [key, public_send(key)] }.freeze
+
+      def self.from_h(value)
+        new(**value.transform_keys(&:to_sym))
+      end
+
+      def with(**changes)
+        values = to_h.merge(changes.transform_keys(&:to_s))
+        values["handoff_revision"] = handoff_revision + 1 unless changes.key?(:handoff_revision)
+        values["updated_at"] = Time.now.utc.iso8601(6) unless changes.key?(:updated_at)
+        self.class.from_h(values)
+      end
+    end
+  end
+end