phronomy 0.22.0 → 0.24.0

data/lib/phronomy/agent/handoff_projection.rb

@@ -0,0 +1,207 @@
+# frozen_string_literal: true
+
+module Phronomy
+  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) || request.is_a?(Snapshot)
+          raise ArgumentError, "request must be a HandoffRequest"
+        end
+        unless manifest.is_a?(Phronomy::Agent::LLMInputManifest)
+          raise ArgumentError, "manifest must be an LLMInputManifest"
+        end
+
+        groups = project_visible_groups(manifest)
+        selected = groups.values.select do |group|
+          include_group?(request, group.fetch(:policy_category))
+        end
+
+        items = selected.flat_map do |group|
+          group.fetch(:segments).map do |segment|
+            materialize_item(
+              segment,
+              policy_category: group.fetch(:policy_category),
+              persistence: persistence,
+              source_agent: source_agent,
+              target_agent: request.handoff.target_agent
+            )
+          end
+        end
+
+        HandoffContext.new(
+          responsibility: request.responsibility,
+          items: items
+        )
+      end
+
+      private
+
+      def project_visible_groups(manifest)
+        groups = {}
+        manifest.segments.each do |segment|
+          policy_category = policy_category_for(segment)
+          next unless policy_category
+
+          key = selection_group_key(segment, policy_category)
+          group = groups[key] ||= {
+            policy_category: policy_category,
+            segments: []
+          }
+          if group[:policy_category] != policy_category
+            raise Phronomy::HandoffError,
+              "one Handoff projection group spans incompatible policy categories"
+          end
+          group[:segments] << segment
+        end
+        groups
+      end
+
+      def policy_category_for(segment)
+        explicit = segment.metadata["handoff_policy_category"] ||
+          segment.metadata[:handoff_policy_category]
+        return explicit.to_sym if explicit
+
+        semantic_category =
+          segment.metadata["context_policy_semantic_category"] ||
+          segment.metadata[:context_policy_semantic_category]
+        case semantic_category&.to_sym
+        when :instruction
+          return nil
+        when :knowledge
+          return :knowledge
+        when :conversation
+          return :current_request if segment.delivery.to_sym == :ask_argument
+          return :history
+        end
+
+        return :current_request if segment.delivery.to_sym == :ask_argument
+        return nil if CONTROL_CATEGORIES.include?(segment.category.to_sym)
+        return :knowledge if segment.category.to_sym == :knowledge
+        unit_kind = segment.metadata["selection_unit_kind"] ||
+          segment.metadata[:selection_unit_kind]
+        return :tool_exchanges if unit_kind.to_s == "tool_exchange"
+
+        case segment.category.to_sym
+        when :external_message, :assistant_message, :tool_message,
+             :conversation, :memory, :summary, :structured_state
+          :history
+        end
+      end
+
+      def selection_group_key(segment, policy_category)
+        conversation_group_id =
+          segment.metadata["context_policy_conversation_group_id"] ||
+          segment.metadata[:context_policy_conversation_group_id]
+        if conversation_group_id
+          return "context-policy-conversation:#{conversation_group_id}"
+        end
+
+        # Compatibility for finalized pre-ACS-04 manifests. New manifests use
+        # context_policy_conversation_group_id and do not recreate Selection::Unit.
+        unit_id = segment.metadata["selection_unit_id"] ||
+          segment.metadata[:selection_unit_id]
+        return "unit:#{unit_id}" if unit_id
+
+        "segment:#{policy_category}:#{segment.position}"
+      end
+
+      def include_group?(request, category)
+        policy = request.handoff.policy
+        return true if policy.required?(category)
+        return false if policy.forbidden?(category)
+
+        request.selection_intent.fetch(category) do
+          policy.default_include?(category)
+        end
+      end
+
+      def materialize_item(segment, policy_category:, persistence:, source_agent:, target_agent:)
+        bytes = persistence.contents.fetch(segment.content_ref)
+        category = segment.category.to_sym
+        metadata = segment.metadata.to_h.transform_keys(&:to_s)
+        format = content_format_for(segment, metadata)
+        content = (format == :json) ? Phronomy::CanonicalJSON.load(bytes) : bytes.to_s
+        provenance = provenance_for(
+          metadata,
+          segment: segment,
+          source_agent: source_agent,
+          target_agent: target_agent
+        )
+
+        HandoffContext::Item.new(
+          candidate_category: category,
+          policy_category: policy_category,
+          role: segment.role,
+          content: content,
+          content_format: format,
+          tool_call_id: segment.tool_call_id,
+          provenance: provenance,
+          metadata: metadata.except(
+            "context_policy_content_format",
+            "context_policy_conversation_group_id",
+            "selection_candidate_id", "selection_unit_id", "selection_unit_kind",
+            "handoff_policy_category", "handoff_provenance"
+          )
+        )
+      end
+
+      def content_format_for(segment, metadata)
+        explicit = metadata["context_policy_content_format"] ||
+          metadata[:context_policy_content_format]
+        if explicit
+          format = explicit.to_sym
+          unless Phronomy::Agent::ContextPolicyInput::CONTENT_FORMATS.include?(format)
+            raise Phronomy::HandoffError,
+              "unsupported Context content format in Manifest: #{explicit.inspect}"
+          end
+          return format
+        end
+
+        JSON_CATEGORIES.include?(segment.category.to_sym) ? :json : :text
+      end
+
+      def provenance_for(metadata, segment:, source_agent:, target_agent:)
+        inherited = metadata["handoff_provenance"]
+        if inherited
+          base = HandoffContext::Provenance.new(
+            origin_agent_id: inherited["origin_agent_id"] || inherited[:origin_agent_id],
+            origin_record_id: inherited["origin_record_id"] || inherited[:origin_record_id],
+            origin_execution_id: inherited["origin_execution_id"] || inherited[:origin_execution_id],
+            origin_llm_call_id: inherited["origin_llm_call_id"] || inherited[:origin_llm_call_id],
+            origin_tool_call_id: inherited["origin_tool_call_id"] || inherited[:origin_tool_call_id],
+            transfer_path: inherited["transfer_path"] || inherited[:transfer_path]
+          )
+          return base.forwarded_to(target_agent.agent_id)
+        end
+
+        HandoffContext::Provenance.new(
+          origin_agent_id: metadata["source_agent_id"] || source_agent.agent_id,
+          origin_record_id: metadata["journal_record_id"],
+          origin_execution_id: metadata["source_execution_id"],
+          origin_llm_call_id: metadata["llm_call_id"],
+          origin_tool_call_id: segment.tool_call_id,
+          transfer_path: [source_agent.agent_id, target_agent.agent_id]
+        )
+      end
+    end
+  end
+end

data/lib/phronomy/agent/handoff_request.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    # Typed private control request produced from one intercepted Handoff capability.
+    # @api private
+    HandoffRequest = Data.define(
+      :handoff, :responsibility, :selection_intent, :llm_call_id, :tool_call_id
+    ) do
+      def initialize(handoff:, responsibility:, selection_intent:, llm_call_id: nil, tool_call_id: nil)
+        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::Agent::Handoff"
+        end
+
+        normalized = handoff.policy.selectable_categories.to_h do |category|
+          raw = selection_intent.fetch(category) do
+            handoff.policy.default_include?(category)
+          end
+          unless raw == true || raw == false
+            raise ArgumentError,
+              "Handoff selection for #{category.inspect} must be boolean"
+          end
+          [category, raw]
+        end.freeze
+
+        unknown = selection_intent.keys.map(&:to_sym) - handoff.policy.selectable_categories
+        unless unknown.empty?
+          raise ArgumentError,
+            "Handoff selection attempts to override non-selectable categories: #{unknown.inspect}"
+        end
+
+        super(
+          handoff: handoff,
+          responsibility: responsibility.freeze,
+          selection_intent: normalized,
+          llm_call_id: llm_call_id&.to_s&.freeze,
+          tool_call_id: tool_call_id&.to_s&.freeze
+        )
+        freeze
+      end
+    end
+  end
+end

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

data/lib/phronomy/agent/journal_record.rb

@@ -13,7 +13,7 @@ module Phronomy
     class JournalRecord
       ATTRIBUTES = %i[
         record_id agent_id sequence execution_id llm_call_id kind channel role content_ref
-        parent_id causation_id correlation_id visibility context_generation
+        parent_id causation_id visibility context_generation
         context_candidate occurred_at metadata
       ].freeze
 
@@ -31,7 +31,6 @@ module Phronomy
         content_ref: nil,
         parent_id: nil,
         causation_id: nil,
-        correlation_id: nil,
         visibility: :agent,
         context_generation: 0,
         context_candidate: false,
@@ -52,14 +51,28 @@ module Phronomy
         self.class.from_h(to_h.merge("sequence" => sequence))
       end
 
+      # Current semantic payload representation. Persistence format identity and
+      # compatibility validation are owned by Persistence::DurableCodec.
       def to_h
         ATTRIBUTES.to_h { |name| [name.to_s, public_send(name)] }
       end
 
+      # Historical durable fields are not accepted here. Explicit migration must
+      # convert them to the current semantic payload first.
       def self.from_h(hash)
+        source = hash.to_h { |key, value| [key.to_s, value] }
+        expected = ATTRIBUTES.map(&:to_s).sort
+        actual = source.keys.sort
+        unless actual == expected
+          missing = expected - actual
+          unknown = actual - expected
+          raise ArgumentError,
+            "JournalRecord payload schema mismatch: " \
+            "missing=#{missing.inspect}, unknown=#{unknown.inspect}"
+        end
+
         new(**ATTRIBUTES.to_h do |name|
-          key = hash.key?(name.to_s) ? name.to_s : name
-          [name, hash[key]]
+          [name, source.fetch(name.to_s)]
         end)
       end
     end

data/lib/phronomy/agent/llm_input_build_context.rb

@@ -5,7 +5,7 @@ module Phronomy
     # Immutable metadata passed to before_llm_input hooks. Runtime objects such
     # as RubyLLM::Chat, messages and the mutable Agent instance are not exposed.
     LLMInputBuildContext = Data.define(
-      :agent_id, :agent_definition_id, :definition_version,
+      :agent_id, :agent_definition_id, :agent_definition_version,
       :config, :call_sequence
     ) do
       def initialize(**values)