phronomy 0.22.0 → 0.23.0

data/lib/phronomy/engine/runtime.rb

@@ -3,21 +3,15 @@
 require_relative "runtime/timer_queue"
 require_relative "runtime/shutdown_result"
 require_relative "runtime/timer_service"
+require_relative "runtime/agent_ownership_registry"
 
 module Phronomy
-  # Owns the EventLoop, offloaded synchronous work, timers and shutdown lifecycle.
-  #
-  # Runtime no longer schedules arbitrary Tasks. Framework control flow belongs
-  # to EventLoop/FSMSession; synchronous work that must not run on the EventLoop
-  # belongs to OffloadPool.
   class Runtime
     @instance_mutex = Mutex.new
 
     class << self
       def instance
-        instance_mutex.synchronize do
-          @instance ||= new
-        end
+        instance_mutex.synchronize { @instance ||= new }
       end
 
       def default_if_initialized_for_test
@@ -69,7 +63,8 @@ module Phronomy
       @pool_registry = Phronomy::Concurrency::PoolRegistry.new(
         timer_queue_provider: -> { timer_queue }
       )
-      @agent_activations = Phronomy::Agent::ActivationRegistry.new
+      @multi_agent_admissions = Phronomy::MultiAgent::AdmissionRegistry.new
+      @agent_ownership_registry = AgentOwnershipRegistry.new(runtime: self)
       @lifecycle_mutex = Mutex.new
       @shutdown_mutex = Mutex.new
       @state = :running
@@ -95,7 +90,6 @@ module Phronomy
       @pool_registry.named_pool(name, size: size, queue_size: queue_size)
     end
 
-    # Public timer access also ensures that the EventLoop that drives timers is alive.
     def timer_queue
       ensure_accepting_work!
       timer = @timer_service.timer_queue
@@ -103,15 +97,77 @@ module Phronomy
       timer
     end
 
-    # Internal EventLoop access that does not recursively initialise EventLoop.
     def __timer_queue
       @timer_service.timer_queue
     end
 
-    # Process-local live Agent executions. Activations are transient runtime
-    # state and deliberately do not belong to Persistence.
-    def __agent_activations
-      @agent_activations
+    # Returns only an immutable process-local routing/ownership view. Mutable
+    # execution state remains inside EventLoop and is never exposed to callers.
+    # @api private
+    def __agent_execution_owner(execution_id)
+      loop_instance = @lifecycle_mutex.synchronize { @event_loop }
+      loop_instance&.agent_execution_owner(execution_id)
+    end
+
+    # @api private
+    def __create_agent(agent_id, expected_class:, &block)
+      @agent_ownership_registry.create(agent_id, expected_class: expected_class, &block)
+    end
+
+    # @api private
+    def __load_agent(agent_id, expected_class:, &block)
+      @agent_ownership_registry.load(agent_id, expected_class: expected_class, &block)
+    end
+
+    # @api private
+    def __get_agent(agent_id, expected_class:)
+      @agent_ownership_registry.get(agent_id, expected_class: expected_class)
+    end
+
+    # @api private
+    def __agent_owned?(agent)
+      @agent_ownership_registry.owned?(agent)
+    end
+
+    # @api private
+    def __begin_agent_purge(agent)
+      @agent_ownership_registry.begin_purge(agent)
+    end
+
+    # @api private
+    def __complete_agent_purge(agent, token)
+      @agent_ownership_registry.complete_purge(agent, token)
+    end
+
+    # @api private
+    def __abort_agent_purge(agent, token)
+      @agent_ownership_registry.abort_purge(agent, token)
+    end
+
+    # @api private
+    def __leave_agent_purge_uncertain(agent, token)
+      @agent_ownership_registry.leave_purge_uncertain(agent, token)
+    end
+
+    # @api private
+    def __agent_execution_admitted?(agent_id)
+      loop_instance = @lifecycle_mutex.synchronize { @event_loop }
+      loop_instance&.agent_execution_admitted?(agent_id) || false
+    end
+
+    # @api private
+    def __admit_multi_agent(coordinator)
+      current_state = @lifecycle_mutex.synchronize { @state }
+      unless current_state == :running
+        raise Phronomy::RuntimeShutdownError,
+          "Runtime is #{current_state}; new Multi-Agent turns are not accepted"
+      end
+      @multi_agent_admissions.admit!(coordinator)
+    end
+
+    # @api private
+    def __release_multi_agent(coordinator)
+      @multi_agent_admissions.release!(coordinator)
     end
 
     def event_loop
@@ -163,23 +219,22 @@ module Phronomy
       @shutdown_mutex.synchronize do
         return @shutdown_result if @shutdown_result
 
-        # Phase 1 — drain sessions with the full configured grace.
         drain_deadline = monotonic_now + timeout
         loop_instance = @lifecycle_mutex.synchronize do
           @state = :draining unless @state == :failed
           @event_loop
         end
         loop_instance&.begin_draining
+        @agent_ownership_registry.begin_draining
 
+        admission_idle = @multi_agent_admissions.wait_until_idle(drain_deadline)
+        agent_ownership_stable = @agent_ownership_registry.wait_until_stable(drain_deadline)
         loop_idle = !loop_instance || loop_instance.wait_until_idle(drain_deadline)
 
         @lifecycle_mutex.synchronize do
           @state = :stopping unless @state == :failed
         end
 
-        # Phase 2 — stop the EventLoop thread with a short independent budget.
-        # An idle EventLoop processes STOP and exits in < 1ms normally; the 0.2s
-        # budget here is only a safety net for OS scheduling jitter.
         stop_deadline = monotonic_now + [cancel_grace.to_f, 0.2].max
         event_loop_status = if loop_instance
           loop_instance.stop_and_join(deadline: stop_deadline)
@@ -188,7 +243,7 @@ module Phronomy
         end
 
         subsystem_error = shutdown_pools_and_timer
-        cleanup_complete = loop_idle &&
+        cleanup_complete = admission_idle && agent_ownership_stable && loop_idle &&
           (!loop_instance || !loop_instance.thread_alive?) &&
           event_loop_status != :cancel_timeout &&
           subsystem_error.nil?
@@ -200,6 +255,8 @@ module Phronomy
           :terminated
         end
 
+        @agent_ownership_registry.shutdown! if cleanup_complete
+
         result = ShutdownResult.new(
           runtime_outcome: runtime_outcome,
           cleanup_status: cleanup_complete ? :complete : :incomplete,

data/lib/phronomy/generator_verifier.rb

@@ -159,7 +159,7 @@ module Phronomy
           feedback = next_state.review_notes.last
           prompt = draft_prompt_builder.call(next_state.input, feedback)
 
-          draft_agent.invoke_async(
+          draft_agent.send(:__invoke_async_with_event_sink,
             prompt,
             on_event: ->(agent_event) {
               case agent_event.type
@@ -169,7 +169,7 @@ module Phronomy
                     agent_event.payload[:output]
                   )
                   workflow.signal(
-                    thread_id: next_state.thread_id,
+                    workflow_instance_id: next_state.workflow_instance_id,
                     event: :draft_completed,
                     payload: {
                       request_id: request_id,
@@ -186,7 +186,7 @@ module Phronomy
                   )
                 rescue => error
                   workflow.signal(
-                    thread_id: next_state.thread_id,
+                    workflow_instance_id: next_state.workflow_instance_id,
                     event: :draft_failed,
                     payload: {
                       request_id: request_id,
@@ -196,7 +196,7 @@ module Phronomy
                 end
               when :error, :timeout, :cancelled
                 workflow.signal(
-                  thread_id: next_state.thread_id,
+                  workflow_instance_id: next_state.workflow_instance_id,
                   event: :draft_failed,
                   payload: {
                     request_id: request_id,
@@ -209,7 +209,7 @@ module Phronomy
                 )
               when :approval_required
                 workflow.signal(
-                  thread_id: next_state.thread_id,
+                  workflow_instance_id: next_state.workflow_instance_id,
                   event: :draft_failed,
                   payload: {
                     request_id: request_id,
@@ -219,8 +219,7 @@ module Phronomy
                   }
                 )
               end
-            }
-          )
+            })
 
           next_state
         }
@@ -234,7 +233,7 @@ module Phronomy
             next_state.citations
           )
 
-          review_agent.invoke_async(
+          review_agent.send(:__invoke_async_with_event_sink,
             prompt,
             on_event: ->(agent_event) {
               case agent_event.type
@@ -244,7 +243,7 @@ module Phronomy
                     agent_event.payload[:output]
                   )
                   workflow.signal(
-                    thread_id: next_state.thread_id,
+                    workflow_instance_id: next_state.workflow_instance_id,
                     event: :review_completed,
                     payload: {
                       request_id: request_id,
@@ -258,7 +257,7 @@ module Phronomy
                   )
                 rescue => error
                   workflow.signal(
-                    thread_id: next_state.thread_id,
+                    workflow_instance_id: next_state.workflow_instance_id,
                     event: :review_failed,
                     payload: {
                       request_id: request_id,
@@ -268,7 +267,7 @@ module Phronomy
                 end
               when :error, :timeout, :cancelled
                 workflow.signal(
-                  thread_id: next_state.thread_id,
+                  workflow_instance_id: next_state.workflow_instance_id,
                   event: :review_failed,
                   payload: {
                     request_id: request_id,
@@ -281,7 +280,7 @@ module Phronomy
                 )
               when :approval_required
                 workflow.signal(
-                  thread_id: next_state.thread_id,
+                  workflow_instance_id: next_state.workflow_instance_id,
                   event: :review_failed,
                   payload: {
                     request_id: request_id,
@@ -291,8 +290,7 @@ module Phronomy
                   }
                 )
               end
-            }
-          )
+            })
 
           next_state
         }

data/lib/phronomy/invocation_context.rb

@@ -1,56 +1,43 @@
 # frozen_string_literal: true
 
 module Phronomy
-  # Carries all per-invocation context values through the call stack.
+  # Carries per-invocation control, policy, and tracing context through the call stack.
   #
   # +InvocationContext+ is a plain struct-like value carrier that replaces
   # ad-hoc +Thread.current[...]+ propagation.
   # Pass it explicitly wherever context needs to cross a method boundary.
   #
+  # Generic conversation/session identity is deliberately not part of this
+  # object. Use purpose-specific domain identifiers and application tracing
+  # metadata instead.
+  #
   # @example Build a context for a new agent invocation
   #   ctx = Phronomy::InvocationContext.new(
-  #     thread_id: "conv-123",
+  #     task_id: "request-123",
   #     cancellation_token: Phronomy::Concurrency::CancellationToken.timeout_after(30)
   #   )
   #   agent.invoke("Hello", invocation_context: ctx)
   #
   # @api public
   class InvocationContext
-    attr_reader :thread_id, :session_id, :user_id, :cancellation_token,
-      :deadline, :tracer_span, :token_budget, :approval_policy,
-      :redaction_policy, :task_id, :parent_task_id
+    attr_reader :user_id, :cancellation_token, :deadline,
+      :token_budget, :approval_policy, :redaction_policy, :task_id,
+      :parent_task_id
 
-    # @param thread_id [String, nil]
-    # @param session_id [String, nil]
-    # @param user_id [String, nil]
-    # @param cancellation_token [CancellationToken, nil]
-    # @param deadline [Deadline, nil]
-    # @param tracer_span [Object, nil]
-    # @param token_budget [Integer, nil]
-    # @param approval_policy [#call, nil]
-    # @param redaction_policy [Object, nil]
-    # @param task_id [String, nil]
-    # @param parent_task_id [String, nil]
     # @api public
     def initialize(
-      thread_id: nil,
-      session_id: nil,
       user_id: nil,
       cancellation_token: nil,
       deadline: nil,
-      tracer_span: nil,
       token_budget: nil,
       approval_policy: nil,
       redaction_policy: nil,
       task_id: nil,
       parent_task_id: nil
     )
-      @thread_id = thread_id
-      @session_id = session_id
       @user_id = user_id
       @cancellation_token = cancellation_token
       @deadline = deadline
-      @tracer_span = tracer_span
       @token_budget = token_budget
       @approval_policy = approval_policy
       @redaction_policy = redaction_policy
@@ -58,16 +45,12 @@ module Phronomy
       @parent_task_id = parent_task_id
     end
 
-    # Returns a new +InvocationContext+ with the given attributes merged in.
     # @api private
     def merge(**overrides)
       InvocationContext.new(
-        thread_id: overrides.fetch(:thread_id, @thread_id),
-        session_id: overrides.fetch(:session_id, @session_id),
         user_id: overrides.fetch(:user_id, @user_id),
         cancellation_token: overrides.fetch(:cancellation_token, @cancellation_token),
         deadline: overrides.fetch(:deadline, @deadline),
-        tracer_span: overrides.fetch(:tracer_span, @tracer_span),
         token_budget: overrides.fetch(:token_budget, @token_budget),
         approval_policy: overrides.fetch(:approval_policy, @approval_policy),
         redaction_policy: overrides.fetch(:redaction_policy, @redaction_policy),
@@ -76,14 +59,11 @@ module Phronomy
       )
     end
 
-    # Convenience: returns the cancellation token or a new never-cancelled token.
     # @api private
     def effective_cancellation_token
       @cancellation_token || Phronomy::Concurrency::CancellationToken.new
     end
 
-    # Returns the cancellation token to use for an invocation, taking both the
-    # explicit cancellation_token and deadline into account.
     # @api private
     def effective_timeout_token
       return @cancellation_token if @cancellation_token

data/lib/phronomy/multi_agent/admission_registry.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module MultiAgent
+    # Runtime-local admission for one user-facing coordination turn per main Agent.
+    # This owns exclusion only; active-agent mutation still belongs to EventLoop.
+    class AdmissionRegistry
+      def initialize
+        @mutex = Mutex.new
+        @cond = ConditionVariable.new
+        @owners = {}
+      end
+
+      def admit!(coordinator)
+        key = coordinator.object_id
+        @mutex.synchronize do
+          if @owners.key?(key)
+            raise Phronomy::HandoffError,
+              "a Multi-Agent turn is already active for this main Agent instance"
+          end
+          @owners[key] = coordinator
+        end
+        true
+      end
+
+      def release!(coordinator)
+        key = coordinator.object_id
+        @mutex.synchronize do
+          removed = @owners.delete(key)
+          @cond.broadcast if @owners.empty?
+          !removed.nil?
+        end
+      end
+
+      def idle?
+        @mutex.synchronize { @owners.empty? }
+      end
+
+      def wait_until_idle(deadline)
+        @mutex.synchronize do
+          until @owners.empty?
+            remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+            return false if remaining <= 0
+            @cond.wait(@mutex, remaining)
+          end
+          true
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/multi_agent/coordination_state.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module MultiAgent
+    CoordinationState = Data.define(:active_agent, :active_handoff_context) do
+      def initialize(active_agent:, active_handoff_context: nil)
+        unless active_agent.is_a?(Phronomy::Agent::Base)
+          raise ArgumentError, "active_agent must be a Phronomy::Agent::Base"
+        end
+        if active_handoff_context && !active_handoff_context.is_a?(HandoffContext)
+          raise ArgumentError, "active_handoff_context must be a HandoffContext"
+        end
+        super
+        freeze
+      end
+    end
+  end
+end

data/lib/phronomy/multi_agent/coordinator.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module MultiAgent
+    class Coordinator
+      ATTACH_MUTEX = Mutex.new
+      private_constant :ATTACH_MUTEX
+
+      ApplyHandoffCommand = Data.define(:coordinator, :request, :context, :completion)
+
+      attr_reader :main_agent, :handoffs
+
+      def self.attach(main_agent:, handoffs:)
+        unless main_agent.is_a?(Phronomy::Agent::Base)
+          raise ArgumentError, "main_agent must be a Phronomy::Agent::Base"
+        end
+        normalized = Array(handoffs).freeze
+
+        ATTACH_MUTEX.synchronize do
+          existing = main_agent.instance_variable_get(:@_phronomy_multi_agent_coordinator)
+          if existing&.runtime_current?
+            existing.assert_compatible!(normalized)
+            return existing
+          end
+
+          created = new(main_agent: main_agent, handoffs: normalized)
+          main_agent.instance_variable_set(:@_phronomy_multi_agent_coordinator, created)
+          created
+        end
+      end
+
+      def initialize(main_agent:, handoffs:)
+        @main_agent = main_agent
+        @handoffs = Array(handoffs).freeze
+        @runtime = Phronomy::Runtime.instance
+        validate_graph!
+        @bindings_by_source = build_bindings
+        @state_mutex = Mutex.new
+        @state = CoordinationState.new(active_agent: main_agent)
+      end
+
+      def runtime_current?
+        Phronomy::Runtime.instance.equal?(@runtime)
+      end
+
+      def snapshot
+        unless runtime_current?
+          raise Phronomy::RuntimeShutdownError,
+            "Multi-Agent coordination state belongs to a previous Runtime"
+        end
+        @state_mutex.synchronize { @state }
+      end
+
+      def outgoing_bindings(agent)
+        @bindings_by_source.fetch(agent.object_id, []).freeze
+      end
+
+      def transition!(request, context)
+        completion = Phronomy::Task.deferred(name: "multi-agent-handoff")
+        command = ApplyHandoffCommand.new(
+          coordinator: self,
+          request: request,
+          context: context,
+          completion: completion
+        )
+        posted = Phronomy::Runtime.instance.event_loop.post(
+          Phronomy::Event.new(
+            type: :agent_terminal_ready,
+            target_id: Phronomy::EventLoop::SYSTEM_CHANNEL_ID,
+            payload: {command: command}
+          )
+        )
+        unless posted
+          completion.fail(
+            Phronomy::RuntimeShutdownError.new(
+              "EventLoop is not accepting Multi-Agent Handoff transitions"
+            )
+          )
+        end
+        completion.wait_result
+      end
+
+      # @api private
+      def deliver_on_event_loop(command)
+        runtime = Phronomy::Runtime.instance
+        unless runtime.event_loop.current?
+          raise Phronomy::Error,
+            "Multi-Agent coordination state may only be mutated on EventLoop"
+        end
+
+        request = command.request
+        context = command.context
+        current = snapshot
+        unless request.handoff.source_agent.equal?(current.active_agent)
+          raise Phronomy::HandoffError,
+            "Handoff source is no longer the active Agent"
+        end
+
+        next_state = CoordinationState.new(
+          active_agent: request.handoff.target_agent,
+          active_handoff_context: context
+        )
+        @state_mutex.synchronize { @state = next_state }
+        command.completion.complete(next_state)
+      rescue => error
+        command.completion.fail(error)
+      end
+
+      def assert_compatible!(handoffs)
+        incoming = graph_signature(handoffs)
+        current = graph_signature(@handoffs)
+        return true if incoming == current
+
+        raise Phronomy::ConfigurationError,
+          "a MultiAgent::Runner for this main Agent already exists with a different Handoff graph"
+      end
+
+      private
+
+      def validate_graph!
+        unless @handoffs.all? { |handoff| handoff.is_a?(Handoff) }
+          raise ArgumentError, "handoffs must contain only MultiAgent::Handoff values"
+        end
+
+        duplicates = @handoffs.group_by do |handoff|
+          [handoff.source_agent.object_id, handoff.target_agent.object_id]
+        end.select { |_key, values| values.length > 1 }
+        unless duplicates.empty?
+          raise ArgumentError, "duplicate Source → Target Handoff edges are not allowed"
+        end
+      end
+
+      def build_bindings
+        @handoffs.group_by(&:source_agent).to_h do |source, edges|
+          [
+            source.object_id,
+            edges.map { |handoff| HandoffCapabilityFactory.build(handoff) }.freeze
+          ]
+        end.freeze
+      end
+
+      def graph_signature(handoffs)
+        Array(handoffs).map do |handoff|
+          [
+            handoff.source_agent.object_id,
+            handoff.target_agent.object_id,
+            handoff.policy.to_h,
+            handoff.description
+          ]
+        end.sort_by { |row| [row[0], row[1], row[3]] }
+      end
+    end
+  end
+end