phronomy 0.22.0 → 0.23.0

data/lib/phronomy/multi_agent/execution_coordinator.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module MultiAgent
+    # 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
+      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
+        return commit_failed_outcome(operation, view.source_error) if view.source_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
+        commit_failed_outcome(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|
+          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"
+          )
+          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/multi_agent/fan_out_invocation.rb

@@ -1,17 +1,14 @@
 # frozen_string_literal: true
 
-require "securerandom"
-
 module Phronomy
   module MultiAgent
     # Mutable FSM context for one fan-out operation.
     class FanOutInvocation
-      Child = Data.define(:index, :agent, :input, :config, :thread_id)
+      Child = Data.define(:index, :agent, :input, :config)
 
-      attr_reader :id, :phase, :results
+      attr_reader :phase, :results
 
       def initialize(children:, max_concurrency:, on_error:)
-        @id = SecureRandom.uuid.to_s
         @phase = nil
         @children = children
         @max_concurrency = max_concurrency || children.length
@@ -19,15 +16,13 @@ module Phronomy
         @pending = children.dup
         @active = {}
         @results = Array.new(children.length)
-        @child_errors = Array.new(children.length)  # indexed by input order
-        @fatal_error = nil   # driver_failed / timeout / cancel
+        @child_errors = Array.new(children.length)
+        @fatal_error = nil
         @cancelled = false
         @timed_out = false
-        @session_id = nil
       end
 
-      def set_graph_metadata(thread_id: nil, phase: nil)
-        @session_id = thread_id if thread_id
+      def set_graph_metadata(phase: nil)
         @phase = phase
       end
 
@@ -41,9 +36,6 @@ module Phronomy
           if child_error
             if @on_error == :raise
               @child_errors[index] = child_error
-              # Signal cancellation so other children can stop early, but continue
-              # waiting for all active children to respond so we can return the
-              # first error in INPUT ORDER (not arrival order).
               cancel_active_children! unless @child_errors.any?(&:itself)
             end
           else
@@ -69,27 +61,28 @@ module Phronomy
         end
       end
 
-      def start_available!(runtime)
+      def start_available!(runtime, event_sink:)
         return self if @fatal_error
 
         while @active.length < @max_concurrency && (child = @pending.shift)
           child_config = build_child_config(child.config)
           handle = child.agent.invoke_async(
             child.input,
-            config: child_config,
-            thread_id: child.thread_id
+            config: child_config
           )
-          @active[child.index] = {handle: handle, token: child_config[:cancellation_token]}
-          # [child.index].each creates a block parameter with a unique binding
-          # per iteration, avoiding the while-loop variable capture problem.
+          @active[child.index] = {
+            handle: handle,
+            token: child_config[:cancellation_token]
+          }
           [child.index].each do |captured_index|
             handle.on_complete do |result, error|
-              runtime.event_loop.post_to_session(
-                Phronomy::Event.new(
-                  type: :child_completed,
-                  target_id: @id,
-                  payload: {index: captured_index, result: result, error: error}
-                )
+              event_sink.post(
+                :child_completed,
+                {
+                  index: captured_index,
+                  result: result,
+                  error: error
+                }
               )
             end
           end
@@ -98,13 +91,7 @@ module Phronomy
       rescue => caught
         @fatal_error ||= caught
         cancel_active_children!
-        runtime.event_loop.post_to_session(
-          Phronomy::Event.new(
-            type: :driver_failed,
-            target_id: @id,
-            payload: {error: caught}
-          )
-        )
+        event_sink.post(:driver_failed, {error: caught})
         self
       end
 
@@ -114,7 +101,11 @@ module Phronomy
 
       def failed?
         return true if @fatal_error
-        @on_error == :raise && @pending.empty? && @active.empty? && @child_errors.any?(&:itself)
+
+        @on_error == :raise &&
+          @pending.empty? &&
+          @active.empty? &&
+          @child_errors.any?(&:itself)
       end
 
       def error

data/lib/phronomy/multi_agent/fan_out_session_builder.rb

@@ -16,14 +16,15 @@ module Phronomy
         cancellation_token: nil,
         runtime: Phronomy::Runtime.instance
       )
-        result = Phronomy::Task.deferred(name: "fan-out:#{invocation.id}")
+        result = Phronomy::Task.deferred(name: "fan-out")
 
         if cancellation_token&.cancelled?
           result.fail(Phronomy::CancellationError.new("fan-out cancelled"))
           return result
         end
 
-        source = Phronomy::Task.deferred(name: "fan-out-source:#{invocation.id}")
+        session = build(invocation: invocation, runtime: runtime)
+        source = Phronomy::Task.deferred(name: "fan-out-source:#{session.id}")
         source.on_complete do |context, error|
           if error
             result.fail(error)
@@ -34,27 +35,18 @@ module Phronomy
           end
         end
 
-        session = build(invocation: invocation, runtime: runtime)
         runtime.event_loop.register(session, completion: source)
-
         if timeout
           runtime.timer_queue.schedule(seconds: timeout) do
-            runtime.event_loop.post_to_session(
-              Phronomy::Event.new(
-                type: :timeout,
-                target_id: invocation.id,
-                payload: {message: "dispatch_parallel timed out after #{timeout}s"}
-              )
+            session.event_sink.post(
+              :timeout,
+              {message: "dispatch_parallel timed out after #{timeout}s"}
             )
           end
         end
-
         cancellation_token&.on_cancel do
-          runtime.event_loop.post_to_session(
-            Phronomy::Event.new(type: :cancel, target_id: invocation.id, payload: nil)
-          )
+          session.event_sink.post(:cancel, nil)
         end
-
         result
       rescue => error
         result ||= Phronomy::Task.deferred(name: "fan-out:registration")
@@ -63,7 +55,8 @@ module Phronomy
       end
 
       def self.build(invocation:, runtime:)
-        phase_machine = build_phase_machine(runtime)
+        event_sink = Phronomy::FSMSession::EventSink.new(event_loop: runtime.event_loop)
+        phase_machine = build_phase_machine(runtime, event_sink)
         external_events = {
           child_completed: [{from: :running, to: :running, guard: nil}],
           driver_failed: [{from: :running, to: :failed, guard: nil}],
@@ -72,8 +65,8 @@ module Phronomy
         }
 
         Phronomy::FSMSession.new(
-          id: invocation.id,
           context: invocation,
+          event_sink: event_sink,
           entry_point: :idle,
           entry_actions: {},
           auto_state_set: AUTO_STATE_SET,
@@ -87,7 +80,7 @@ module Phronomy
       end
       private_class_method :build
 
-      def self.build_phase_machine(runtime)
+      def self.build_phase_machine(runtime, event_sink)
         Class.new do
           attr_accessor :context, :current_event
 
@@ -114,7 +107,7 @@ module Phronomy
             event(:cancel) { transition running: :cancelled }
 
             after_transition to: :running do |machine|
-              machine.context.start_available!(runtime)
+              machine.context.start_available!(runtime, event_sink: event_sink)
             end
           end
         end

data/lib/phronomy/multi_agent/handoff.rb

@@ -4,60 +4,39 @@ require "securerandom"
 
 module Phronomy
   module MultiAgent
-    # Represents a transfer edge from one agent to another.
-    # Creates an anonymous Phronomy::Agent::Context::Capability::Base subclass that the source agent
-    # exposes to the LLM as a +transfer_to_<name>+ function.
-    # The tool's execute method returns a sentinel string that Runner uses to
-    # detect which target agent to route to next.
-    #
-    # @example
-    #   billing = BillingAgent.new
-    #   handoff = Phronomy::MultiAgent::Handoff.new(target_agent: billing)
-    #   tool_class = handoff.to_tool_class
+    # Application-defined semantic edge for transferring active responsibility
+    # from one live Agent instance to another.
     class Handoff
-      # Prefix embedded in tool results so Runner can detect handoffs.
-      SENTINEL_PREFIX = "__PHRONOMY_HANDOFF__"
+      attr_reader :source_agent, :target_agent, :policy, :description
 
-      attr_reader :target_agent, :tool_name, :description
-
-      # @param target_agent [Phronomy::Agent::Base] the agent to hand off to
-      # @param description  [String, nil] overrides the auto-generated tool description
-      # @api public
-      def initialize(target_agent:, description: nil)
-        @target_agent = target_agent
-        klass_name = target_agent.class.name&.split("::")&.last || "Agent"
-        # Use a UUID so that two handoffs targeting the same class remain distinct.
-        @uuid = SecureRandom.uuid
-        @tool_name = "transfer_to_#{snake_case(klass_name)}_#{@uuid.delete("-")[0, 8]}"
-        @description = description || "Transfer the conversation to #{klass_name}."
-      end
-
-      # Builds an anonymous Phronomy::Agent::Context::Capability::Base subclass for this handoff.
-      # @return [Class<Phronomy::Agent::Context::Capability::Base>]
       # @api public
-      def to_tool_class
-        sentinel_value = sentinel
-        tn = tool_name
-        desc = description
-        Class.new(Phronomy::Agent::Context::Capability::Base) do
-          tool_name tn
-          description desc
-          execution_mode :cooperative
-          define_method(:execute) { sentinel_value }
+      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::MultiAgent::HandoffPolicy"
         end
-      end
 
-      # The sentinel string embedded in the tool result.
-      # @return [String]
-      # @api public
-      def sentinel
-        "#{SENTINEL_PREFIX}:#{target_agent.class.name}:#{@uuid}"
+        @source_agent = source_agent
+        @target_agent = target_agent
+        @policy = policy
+        @description = (description || default_description).to_s.freeze
+        @transport_key = SecureRandom.hex(8).freeze
+        freeze
       end
 
       private
 
-      def snake_case(klass_name)
-        klass_name.gsub(/([A-Z])/) { "_#{$1}" }.downcase.delete_prefix("_")
+      attr_reader :transport_key
+
+      def default_description
+        target_name = target_agent.class.name || "target Agent"
+        "Transfer active responsibility to #{target_name}."
       end
     end
   end

data/lib/phronomy/multi_agent/handoff_capability_factory.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require "weakref"
+
+module Phronomy
+  module MultiAgent
+    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)
+          freeze
+        end
+      end
+
+      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}"
+        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 = 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
+      end
+      private_class_method :class_slug
+    end
+  end
+end

data/lib/phronomy/multi_agent/handoff_context.rb

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