phronomy 0.22.0 → 0.24.0

data/lib/phronomy/agent/handoff.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Phronomy
+  module Agent
+    # Application-defined semantic edge for transferring active responsibility
+    # from one live Agent instance to another.
+    class Handoff
+      attr_reader :source_agent, :target_agent, :policy, :description
+
+      # @api public
+      def initialize(source_agent:, target_agent:, policy: HandoffPolicy.default, description: nil)
+        unless source_agent.is_a?(Phronomy::Agent::Base) &&
+            target_agent.is_a?(Phronomy::Agent::Base)
+          raise ArgumentError, "source_agent and target_agent must be Agent::Base instances"
+        end
+        if source_agent.equal?(target_agent)
+          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::Agent::HandoffPolicy"
+        end
+
+        @source_agent = source_agent
+        @target_agent = target_agent
+        @policy = policy
+        @description = (description || default_description).to_s.freeze
+        @transport_key = Digest::SHA256.hexdigest([source_agent.agent_id, target_agent.agent_id].join("\0"))[0, 32].freeze
+        freeze
+      end
+
+      private
+
+      attr_reader :transport_key
+
+      def default_description
+        target_name = target_agent.class.name || "target Agent"
+        "Transfer active responsibility to #{target_name}."
+      end
+    end
+  end
+end

data/lib/phronomy/agent/handoff_capability_factory.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    class HandoffCapabilityFactory
+      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)
+          freeze
+        end
+      end
+
+      def self.build(handoff)
+        key = handoff.send(:transport_key)
+        tool_name = "phronomy_handoff_#{key}"
+        description = handoff.description
+        policy = handoff.policy
+
+        klass = Class.new(Phronomy::Agent::Context::Capability::Base) do
+          self.tool_name(tool_name)
+          self.description(description)
+          execution_mode :cooperative
+          param :responsibility,
+            type: :string,
+            required: true,
+            desc: "The concrete responsibility the target Agent must continue."
+
+          policy.selectable_categories.each do |category|
+            param :"include_#{category}",
+              type: :boolean,
+              required: false,
+              desc: "Whether to transfer selectable #{category} Context."
+          end
+
+          define_method(:execute) do |**_args|
+            raise Phronomy::HandoffError,
+              "Handoff capabilities are control-plane operations and must not execute as Tools"
+          end
+        end
+
+        Binding.new(handoff: handoff, tool_class: klass, tool_name: tool_name)
+      end
+    end
+  end
+end

data/lib/phronomy/agent/handoff_context.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    class HandoffContext
+      Provenance = Data.define(
+        :origin_agent_id,
+        :origin_record_id,
+        :origin_execution_id,
+        :origin_llm_call_id,
+        :origin_tool_call_id,
+        :transfer_path
+      ) do
+        def initialize(**values)
+          super(**values.merge(
+            origin_agent_id: values[:origin_agent_id]&.to_s&.freeze,
+            origin_record_id: values[:origin_record_id]&.to_s&.freeze,
+            origin_execution_id: values[:origin_execution_id]&.to_s&.freeze,
+            origin_llm_call_id: values[:origin_llm_call_id]&.to_s&.freeze,
+            origin_tool_call_id: values[:origin_tool_call_id]&.to_s&.freeze,
+            transfer_path: Array(values[:transfer_path]).map(&:to_s).freeze
+          ))
+          freeze
+        end
+
+        def forwarded_to(agent_id)
+          self.class.new(
+            origin_agent_id: origin_agent_id,
+            origin_record_id: origin_record_id,
+            origin_execution_id: origin_execution_id,
+            origin_llm_call_id: origin_llm_call_id,
+            origin_tool_call_id: origin_tool_call_id,
+            transfer_path: transfer_path + [agent_id.to_s]
+          )
+        end
+
+        def to_h
+          {
+            "origin_agent_id" => origin_agent_id,
+            "origin_record_id" => origin_record_id,
+            "origin_execution_id" => origin_execution_id,
+            "origin_llm_call_id" => origin_llm_call_id,
+            "origin_tool_call_id" => origin_tool_call_id,
+            "transfer_path" => transfer_path
+          }.compact.freeze
+        end
+      end
+
+      Item = Data.define(
+        :candidate_category,
+        :policy_category,
+        :role,
+        :content,
+        :content_format,
+        :tool_call_id,
+        :provenance,
+        :metadata
+      ) do
+        def initialize(**values)
+          provenance = values.fetch(:provenance)
+          unless provenance.is_a?(Provenance)
+            raise ArgumentError, "HandoffContext::Item provenance must be Provenance"
+          end
+          format = (values[:content_format] || :text).to_sym
+          unless %i[text json].include?(format)
+            raise ArgumentError, "unsupported Handoff Context content format: #{format.inspect}"
+          end
+          super(**values.merge(
+            candidate_category: values.fetch(:candidate_category).to_sym,
+            policy_category: values.fetch(:policy_category).to_sym,
+            role: values[:role]&.to_sym,
+            content: Phronomy::Agent::Immutable.copy(values.fetch(:content)),
+            content_format: format,
+            tool_call_id: values[:tool_call_id]&.to_s&.freeze,
+            provenance: provenance,
+            metadata: Phronomy::Agent::Immutable.copy(values[:metadata] || {})
+          ))
+          freeze
+        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: [])
+        @responsibility = responsibility.to_s.freeze
+        @items = Array(items).freeze
+        raise ArgumentError, "Handoff Context responsibility must not be empty" if @responsibility.strip.empty?
+        unless @items.all? { |item| item.is_a?(Item) }
+          raise ArgumentError, "Handoff Context items must be HandoffContext::Item values"
+        end
+        freeze
+      end
+    end
+  end
+end

data/lib/phronomy/agent/handoff_execution_coordinator.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Phronomy
+  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 HandoffExecutionCoordinator < Phronomy::Agent::ExecutionCoordinator
+      private
+
+      def compute_terminal(operation)
+        view = operation.terminal_view
+        if view.callback_failure
+          return commit_failed_outcome(
+            operation,
+            view.callback_failure.to_stream_callback_error
+          )
+        end
+        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
+        raise view.invocation_error if view.invocation_error
+
+        return commit_handed_off(operation) if view.handoff
+
+        commit_completed(operation)
+      rescue => caught
+        reconcile_terminal_error(operation, caught)
+      end
+
+      def commit_handed_off(operation)
+        current = operation.execution
+        root = operation.root
+        runtime_snapshot = operation.runtime_snapshot
+        request = operation.terminal_view.handoff
+        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,
+            snapshot: runtime_snapshot,
+            context_candidate: false,
+            agent_root: root
+          )
+          audit_ref = tx.contents.put_json(
+            "target_agent_id" => request.target_agent_id,
+            "responsibility" => request.responsibility,
+            "selection_intent" => request.selection_intent.to_h do |category, included|
+              [category.to_s, included]
+            end
+          )
+          audit_record = Phronomy::Agent::JournalRecord.new(
+            agent_id: @agent.agent_id,
+            execution_id: current.execution_id,
+            llm_call_id: request.llm_call_id,
+            kind: :execution_handed_off,
+            channel: :audit,
+            content_ref: audit_ref,
+            context_generation: root.transcript_generation,
+            context_candidate: false,
+            metadata: {
+              "target_agent_id" => request.target_agent_id,
+              "handoff_tool_call_id" => request.tool_call_id
+            }.compact
+          )
+
+          all_records = current.working_records + encoded_records + [audit_record]
+          appended = tx.journals.append(
+            root.agent_id,
+            expected_position: root.journal_position,
+            records: all_records
+          )
+          handed_off = current.with(
+            status: :handed_off,
+            phase: :handed_off,
+            working_records: [],
+            llm_calls: current.llm_calls + call_records,
+            approval_request: nil,
+            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,
+            expected_revision: current.execution_revision,
+            execution: handed_off
+          )
+          context_changed = appended.any?(&:context_candidate)
+          next_root = root.with(
+            agent_revision: root.agent_revision + 1,
+            context_revision: root.context_revision + (context_changed ? 1 : 0),
+            journal_position: root.journal_position + appended.length,
+            lifecycle_status: :idle
+          )
+          tx.agents.save(
+            root.agent_id,
+            expected_revision: root.agent_revision,
+            root: next_root
+          )
+        end
+
+        result = result_base(handed_off, next_root)
+        TerminalOutcome.new(
+          type: :handed_off,
+          execution: handed_off,
+          root: next_root,
+          appended_records: Array(appended).freeze,
+          result: result.freeze,
+          error: nil,
+          approval_request: nil
+        )
+      end
+    end
+  end
+end

data/lib/phronomy/agent/handoff_policy.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    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
+
+      # 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
+          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