phronomy 0.22.0 → 0.24.0

data/lib/phronomy/engine/runtime/team_ownership_registry.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Phronomy
+  class Runtime
+    # Runtime-local Team identity and construction exclusion; no execution state.
+    # @api private
+    class TeamOwnershipRegistry
+      def initialize
+        @mutex = Mutex.new
+        @condition = ConditionVariable.new
+        @owners = {}
+        @constructing = {}
+        @draining = false
+      end
+
+      def fetch(id, klass:, create:, persistence:)
+        @mutex.synchronize do
+          loop do
+            raise Phronomy::RuntimeShutdownError, "Runtime is draining" if @draining
+            if (owner = @owners[id])
+              raise Phronomy::Persistence::ConflictError, "Team #{id} already exists" if create
+              unless owner.is_a?(klass) && owner.persistence.equal?(persistence)
+                raise Phronomy::ConfigurationError, "Team #{id} owner or Persistence mismatch"
+              end
+              return owner
+            end
+            break unless @constructing[id]
+            @condition.wait(@mutex)
+          end
+          @constructing[id] = true
+        end
+        begin
+          owner = yield
+          @mutex.synchronize { @owners[id] = owner }
+          owner
+        ensure
+          @mutex.synchronize do
+            @constructing.delete(id)
+            @condition.broadcast
+          end
+        end
+      end
+
+      def get(id, klass:)
+        @mutex.synchronize do
+          owner = @owners[id]
+          if owner && !owner.is_a?(klass)
+            raise Phronomy::ConfigurationError, "Team #{id} definition mismatch"
+          end
+          owner
+        end
+      end
+
+      def begin_draining
+        @mutex.synchronize do
+          @draining = true
+          @condition.broadcast
+        end
+      end
+
+      def wait_until_stable(deadline)
+        @mutex.synchronize do
+          until @constructing.empty?
+            remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+            return false if remaining <= 0
+            @condition.wait(@mutex, remaining)
+          end
+          true
+        end
+      end
+
+      def shutdown!
+        @mutex.synchronize { @owners.clear }
+      end
+    end
+  end
+end

data/lib/phronomy/engine/runtime.rb

@@ -3,21 +3,16 @@
 require_relative "runtime/timer_queue"
 require_relative "runtime/shutdown_result"
 require_relative "runtime/timer_service"
+require_relative "runtime/agent_ownership_registry"
+require_relative "runtime/team_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 +64,9 @@ 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)
+      @team_ownership_registry = TeamOwnershipRegistry.new
       @lifecycle_mutex = Mutex.new
       @shutdown_mutex = Mutex.new
       @state = :running
@@ -95,7 +92,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 +99,87 @@ 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 __team_owner(id, klass:, create:, persistence:, &block)
+      @team_ownership_registry.fetch(id, klass: klass, create: create, persistence: persistence, &block)
+    end
+
+    # @api private
+    def __get_team(id, klass:)
+      @team_ownership_registry.get(id.to_s, klass: klass)
+    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 +231,24 @@ 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
+        @team_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)
+        team_ownership_stable = @team_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 +257,7 @@ module Phronomy
         end
 
         subsystem_error = shutdown_pools_and_timer
-        cleanup_complete = loop_idle &&
+        cleanup_complete = admission_idle && agent_ownership_stable && team_ownership_stable && loop_idle &&
           (!loop_instance || !loop_instance.thread_alive?) &&
           event_loop_status != :cancel_timeout &&
           subsystem_error.nil?
@@ -200,6 +269,9 @@ module Phronomy
           :terminated
         end
 
+        @agent_ownership_registry.shutdown! if cleanup_complete
+        @team_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/durable_subagent_coordinator.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Phronomy
+  module MultiAgent
+    # Agent-owned transactions reserve child work; Task callbacks only wake observers.
+    # @api private
+    class DurableSubagentCoordinator
+      KEY = "multi_agent_coordination_ref"
+
+      def self.prepare(parent, execution, tx:)
+        ref = execution.metadata[KEY]
+        snapshot = ref ? tx.contents.fetch_json(ref) : {"kind" => "static_subagent", "children" => []}
+        children = snapshot.fetch("children").map(&:dup)
+        children.each do |child|
+          begin
+            exact = tx.executions.load(child.fetch("execution_id"))
+          rescue Phronomy::Persistence::NotFoundError
+            next
+          end
+          raise Phronomy::Persistence::ConflictError, "Child owner mismatch" unless exact.agent_id == child.fetch("agent_id")
+          child.merge!("state" => exact.status.to_s, "result_ref" => exact.result_ref, "error_ref" => exact.error_ref)
+        end
+        Array(execution.metadata[Phronomy::Agent::RecoverySupport::TOOL_BATCH_METADATA_KEY]).each do |tool|
+          registration = parent.class.registered_subagents.find { |name, _| "dispatch_to_#{name}" == tool.fetch("tool_name") }
+          next unless registration
+          next if children.any? { |child| child.fetch("slot") == tool.fetch("tool_invocation_id") }
+          name, settings = registration
+          definition = settings.fetch(:agent_class).agent_definition
+          knowledge = settings.fetch(:inherit_knowledge) ? parent.send(:active_knowledge_snapshot) : []
+          children << {
+            "slot" => tool.fetch("tool_invocation_id"), "name" => name.to_s,
+            "definition" => definition.transform_keys(&:to_s),
+            "agent_id" => SecureRandom.uuid, "execution_id" => SecureRandom.uuid,
+            "input_ref" => tx.contents.put_text(tool.fetch("arguments").fetch("input")),
+            "durable_context_ref" => execution.metadata["durable_context_ref"],
+            "knowledge_ref" => tx.contents.put_json(Phronomy::Agent::RecoverySupport.canonical_copy(knowledge)),
+            "state" => "reserved", "result_ref" => nil, "error_ref" => nil,
+            "on_error" => settings.fetch(:on_error).to_s
+          }
+        end
+        return execution if children.empty?
+        value = tx.contents.put_json(snapshot.merge("children" => children))
+        execution.with(execution_revision: execution.execution_revision, metadata: execution.metadata.merge(KEY => value))
+      end
+
+      def self.start(parent:, tool_invocation_id:, parent_execution_id:, config:)
+        runtime = Phronomy::Runtime.instance
+        completion = Phronomy::Task.deferred(name: "durable-subagent:#{tool_invocation_id}")
+        preparation = runtime.offload.submit(on_full: :raise) do
+          current = parent.persistence.executions.load(parent_execution_id)
+          raise Phronomy::Persistence::ConflictError, "Parent owner mismatch" unless current.agent_id == parent.agent_id
+          snapshot = parent.persistence.contents.fetch_json(current.metadata.fetch(KEY))
+          child = snapshot.fetch("children").find { |entry| entry.fetch("slot") == tool_invocation_id }
+          raise Phronomy::ExecutionRehydrationRequiredError, "Missing reserved child slot" unless child
+          definition = parent.class.registered_subagents.find { |name, _| name.to_s == child.fetch("name") }&.last
+          unless definition && definition.fetch(:agent_class).agent_definition.transform_keys(&:to_s) == child.fetch("definition")
+            raise Phronomy::ConfigurationError, "Registered child definition changed: #{child.fetch("name")}"
+          end
+          klass = definition.fetch(:agent_class)
+          id = child.fetch("agent_id")
+          agent = klass.get(id)
+          unless agent
+            begin
+              parent.persistence.agents.load(id)
+              exists = true
+            rescue Phronomy::Persistence::NotFoundError
+              exists = false
+            end
+            listener = parent.send(:_phronomy_event_listener)
+            agent = if exists
+              klass.load(id, persistence: parent.persistence, on_event: listener)
+            else
+              knowledge = parent.persistence.contents.fetch_json(child.fetch("knowledge_ref"))
+              context = Phronomy::Agent::ContextImporter::ImportedContext.new(records: knowledge.map do |item|
+                Phronomy::Agent::ContextImporter::ImportedRecord.new(kind: :knowledge,
+                  channel: :context, role: :user, content: item.fetch("content"),
+                  content_format: :text, metadata: item.fetch("metadata"))
+              end)
+              klass.create(agent_id: id, persistence: parent.persistence,
+                context: context, on_event: listener)
+            end
+          end
+          unless agent.persistence.equal?(parent.persistence)
+            raise Phronomy::ConfigurationError, "Child Persistence instance mismatch"
+          end
+          durable_context = child["durable_context_ref"] && parent.persistence.contents.fetch_json(child["durable_context_ref"])
+          [child, agent, parent.persistence.contents.fetch_text(child.fetch("input_ref")), durable_context]
+        end
+        preparation.on_complete do |prepared, failure|
+          if failure
+            completion.fail(Phronomy::ExecutionRehydrationRequiredError.new("Child reservation requires recovery: #{failure.message}"))
+            next
+          end
+          child, agent, input, durable_context = prepared
+          child_config = {cancellation_token: config[:cancellation_token] || Phronomy::Concurrency::CancellationToken.new,
+                          invocation_context: config[:invocation_context],
+                          phronomy_coordination: {"kind" => "subagent", "parent_execution_id" => parent_execution_id,
+                                                  "parent_agent_id" => parent.agent_id, "slot" => tool_invocation_id}}.compact
+          child_config = child_config.merge(durable_context: durable_context) if child["durable_context_ref"]
+          source = Phronomy::Agent::ExactExecution.start(agent: agent,
+            execution_id: child.fetch("execution_id"), input: input, config: child_config)
+          source.on_complete do |result, error|
+            if error
+              if error.is_a?(Phronomy::CancellationError)
+                completion.fail(error)
+              else
+                completion.fail(Phronomy::ExecutionRehydrationRequiredError.new(
+                  "Child #{child.fetch("execution_id")} is unfinished: #{error.message}"
+                ))
+              end
+            elsif result[:error]
+              if child.fetch("on_error") == "skip"
+                completion.complete(nil)
+              else
+                completion.fail(Phronomy::Agent::RecoverySupport.error_from_failure(result[:error]))
+              end
+            else
+              completion.complete(result[:output])
+            end
+          end
+        rescue => error
+          completion.fail(Phronomy::ExecutionRehydrationRequiredError.new("Child coordination requires recovery: #{error.message}"))
+        end
+        completion
+      rescue => error
+        completion ||= Phronomy::Task.deferred(name: "durable-subagent")
+        completion.fail(error)
+        completion
+      end
+    end
+  end
+end