phronomy 0.22.0 → 0.23.0

data/lib/phronomy/multi_agent/handoff_policy.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module MultiAgent
+    class HandoffPolicy
+      CATEGORIES = %i[current_request history knowledge tool_exchanges].freeze
+      MODES = %i[required forbidden selectable].freeze
+      DEFAULTS = %i[include exclude].freeze
+
+      Rule = Data.define(:category, :mode, :default) do
+        def initialize(category:, mode:, default: nil)
+          category = category.to_sym
+          mode = mode.to_sym
+          unless HandoffPolicy::CATEGORIES.include?(category)
+            raise ArgumentError, "unknown Handoff policy category: #{category.inspect}"
+          end
+          unless HandoffPolicy::MODES.include?(mode)
+            raise ArgumentError, "unknown Handoff policy mode: #{mode.inspect}"
+          end
+          if mode == :selectable
+            default = (default || :exclude).to_sym
+            unless HandoffPolicy::DEFAULTS.include?(default)
+              raise ArgumentError, "selectable default must be :include or :exclude"
+            end
+          elsif default
+            raise ArgumentError, "default is valid only for selectable Handoff rules"
+          end
+          super
+          freeze
+        end
+      end
+
+      class Builder
+        def initialize
+          @rules = {}
+        end
+
+        def required(category)
+          set(category, :required)
+        end
+
+        def forbidden(category)
+          set(category, :forbidden)
+        end
+
+        def selectable(category, default: :exclude)
+          set(category, :selectable, default: default)
+        end
+
+        def build
+          missing = CATEGORIES - @rules.keys
+          unless missing.empty?
+            raise ArgumentError,
+              "HandoffPolicy must define all categories; missing: #{missing.inspect}"
+          end
+          HandoffPolicy.new(@rules.values)
+        end
+
+        private
+
+        def set(category, mode, default: nil)
+          category = category.to_sym
+          if @rules.key?(category)
+            raise ArgumentError, "Handoff policy category already defined: #{category.inspect}"
+          end
+          @rules[category] = Rule.new(category: category, mode: mode, default: default)
+          self
+        end
+      end
+
+      private_constant :Rule, :Builder
+
+      def self.define(&block)
+        raise ArgumentError, "HandoffPolicy.define requires a block" unless block
+        builder = Builder.new
+        builder.instance_eval(&block)
+        builder.build
+      end
+
+      def self.default
+        @default ||= define do
+          required :current_request
+          selectable :history, default: :include
+          selectable :knowledge, default: :exclude
+          selectable :tool_exchanges, default: :include
+        end
+      end
+
+      def initialize(rules)
+        @rules = Array(rules).to_h { |rule| [rule.category, rule] }.freeze
+        missing = CATEGORIES - @rules.keys
+        extra = @rules.keys - CATEGORIES
+        unless missing.empty? && extra.empty?
+          raise ArgumentError,
+            "HandoffPolicy categories mismatch; missing=#{missing.inspect} extra=#{extra.inspect}"
+        end
+        freeze
+      end
+
+      def rule(category)
+        @rules.fetch(category.to_sym)
+      end
+
+      def required?(category)
+        rule(category).mode == :required
+      end
+
+      def forbidden?(category)
+        rule(category).mode == :forbidden
+      end
+
+      def selectable?(category)
+        rule(category).mode == :selectable
+      end
+
+      def default_include?(category)
+        selected = rule(category)
+        selected.mode == :required ||
+          (selected.mode == :selectable && selected.default == :include)
+      end
+
+      def selectable_categories
+        CATEGORIES.select { |category| selectable?(category) }.freeze
+      end
+
+      def to_h
+        CATEGORIES.to_h do |category|
+          selected = rule(category)
+          [category.to_s, {
+            "mode" => selected.mode.to_s,
+            "default" => selected.default&.to_s
+          }.compact]
+        end.freeze
+      end
+    end
+  end
+end

data/lib/phronomy/multi_agent/handoff_projection.rb

@@ -0,0 +1,191 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module MultiAgent
+    class HandoffProjection
+      CONTROL_CATEGORIES = %i[instruction handoff_responsibility].freeze
+      JSON_CATEGORIES = %i[assistant_message tool_message].freeze
+
+      def build(request:, manifest:, persistence:, source_agent:)
+        unless request.is_a?(HandoffRequest)
+          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/multi_agent/handoff_request.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module MultiAgent
+    # 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::MultiAgent::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/multi_agent/orchestrator.rb

@@ -50,7 +50,6 @@ module Phronomy
 
             source = agent.invoke_async(
               input,
-              thread_id: ctx[:thread_id] || parent_ic&.thread_id,
               config: task_config
             )
             result_task = Phronomy::Task.deferred(
@@ -151,7 +150,6 @@ module Phronomy
         agent:,
         inputs:,
         config: {},
-        thread_id: nil,
         max_concurrency: nil,
         on_error: :raise,
         timeout: nil,
@@ -161,7 +159,7 @@ module Phronomy
       )
         dispatch_parallel(
           *inputs.map do |input|
-            {agent: agent, input: input, config: config, thread_id: thread_id}
+            {agent: agent, input: input, config: config}
           end,
           max_concurrency: max_concurrency,
           on_error: on_error,
@@ -176,7 +174,6 @@ module Phronomy
         agent:,
         inputs:,
         config: {},
-        thread_id: nil,
         max_concurrency: nil,
         on_error: :raise,
         timeout: nil,
@@ -186,7 +183,7 @@ module Phronomy
       )
         dispatch_parallel_async(
           *inputs.map do |input|
-            {agent: agent, input: input, config: config, thread_id: thread_id}
+            {agent: agent, input: input, config: config}
           end,
           max_concurrency: max_concurrency,
           on_error: on_error,
@@ -201,7 +198,6 @@ module Phronomy
         agent_class,
         input,
         config: nil,
-        thread_id: nil,
         inherit_knowledge: true
       )
         if Phronomy::Runtime.in_event_loop_context?
@@ -213,8 +209,7 @@ module Phronomy
           inherit_knowledge: inherit_knowledge
         ).invoke_async(
           input,
-          config: config || {},
-          thread_id: thread_id
+          config: config || {}
         ).wait_result
       end
 
@@ -233,11 +228,8 @@ module Phronomy
         captured_context = {}
         captured_context[:knowledge] = active_knowledge_snapshot if inherits_knowledge
         if invocation
-          captured_context.merge!(
-            thread_id: invocation.thread_id,
-            config: invocation.config,
-            invocation_context: invocation.config[:invocation_context]
-          )
+          captured_context[:config] = invocation.config
+          captured_context[:invocation_context] = invocation.config[:invocation_context]
         end
         captured_context.freeze
 
@@ -291,6 +283,12 @@ module Phronomy
           raise ArgumentError, "fan-out task must be a Hash" unless task.is_a?(Hash)
           raise ArgumentError, "fan-out task requires :agent" unless task[:agent]
           raise ArgumentError, "fan-out task requires :input" unless task.key?(:input)
+          if task.key?(:thread_id) || task.key?("thread_id")
+            raise ArgumentError,
+              "fan-out task generic thread_id was removed; " \
+              "use purpose-specific domain identifiers or application tracing metadata"
+          end
+          _reject_removed_generic_identity_keys!(task.fetch(:config, {}))
         end
       end
 
@@ -324,8 +322,7 @@ module Phronomy
             index: index,
             agent: child_agent,
             input: task.fetch(:input),
-            config: task_config,
-            thread_id: task[:thread_id] || invocation_context&.thread_id
+            config: task_config
           )
         end
       end

data/lib/phronomy/multi_agent/runner.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module MultiAgent
+    class Runner
+      MAX_HANDOFFS = 20
+
+      attr_reader :main_agent, :handoffs
+
+      # @api public
+      def initialize(main_agent:, handoffs: [])
+        @main_agent = main_agent
+        @handoffs = Array(handoffs).freeze
+        @coordinator = Coordinator.attach(
+          main_agent: main_agent,
+          handoffs: @handoffs
+        )
+      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)
+        )
+        result = nil
+        operation_error = nil
+
+        @coordinator = Coordinator.attach(
+          main_agent: @main_agent,
+          handoffs: @handoffs
+        )
+        runtime = Phronomy::Runtime.instance
+        runtime.__admit_multi_agent(@coordinator)
+        handoffs_taken = 0
+        current_input = input
+
+        result = loop do
+          state = @coordinator.snapshot
+          active_agent = state.active_agent
+          bindings = @coordinator.outgoing_bindings(active_agent)
+          agent_result = active_agent.invoke(
+            current_input,
+            config: config.merge(
+              phronomy_handoff_bindings: bindings,
+              phronomy_handoff_context: state.active_handoff_context
+            )
+          )
+
+          request = agent_result[:handoff_request]
+          break public_result(agent_result, active_agent) unless request
+
+          if handoffs_taken >= MAX_HANDOFFS
+            raise Phronomy::HandoffError,
+              "Exceeded maximum Handoffs (#{MAX_HANDOFFS}) in one user turn"
+          end
+
+          manifest = agent_result.fetch(:_phronomy_handoff_manifest)
+          context = HandoffProjection.new.build(
+            request: request,
+            manifest: manifest,
+            persistence: active_agent.persistence,
+            source_agent: active_agent
+          )
+          @coordinator.transition!(request, context)
+          current_input = request.responsibility
+          handoffs_taken += 1
+        end
+        result
+      rescue => error
+        operation_error = error
+        raise
+      ensure
+        runtime&.__release_multi_agent(@coordinator) if defined?(@coordinator)
+        trace_output = if result.is_a?(Hash)
+          result[:output] || result["output"]
+        else
+          result
+        end
+        Phronomy::Tracing::Automatic.finish(
+          trace_handle,
+          output: trace_output,
+          error: operation_error
+        )
+      end
+
+      private
+
+      def public_result(result, agent)
+        result.reject { |key, _| key.to_s.start_with?("_phronomy_") }
+          .except(:handoff_request)
+          .merge(agent: agent)
+      end
+    end
+  end
+end