phronomy 0.26.0 → 0.28.0

data/lib/phronomy/llm_adapter/request.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require_relative "message"
+
+module Phronomy
+  module LLMAdapter
+    # Immutable input for one model turn, including inert Tool definitions.
+    # @api public
+    class Request
+      attr_reader :model_config, :system, :messages, :tools, :message
+
+      # @api public
+      def initialize(model_config: {}, system: nil, messages: [], tools: [], message: nil)
+        if !(model_config.is_a?(Hash) && (system.nil? || system.is_a?(String)) && (message.nil? || message.is_a?(String)))
+          raise ArgumentError, "invalid LLM request configuration or text"
+        end
+        unless messages.is_a?(Array) && messages.all? { |item| item.is_a?(Message) }
+          raise ArgumentError, "LLM request messages must be Message values"
+        end
+        unless tools.is_a?(Array) && tools.all? { |tool| tool.is_a?(Hash) }
+          raise ArgumentError, "LLM request tools must be definition Hashes"
+        end
+        normalized_tools = tools.map do |definition|
+          definition = normalize_keys(definition)
+          name = definition["name"]
+          unless name.is_a?(String) && !name.empty? && definition["description"].is_a?(String)
+            raise ArgumentError, "Tool definition requires name and description"
+          end
+          if definition.key?("provider_options") && !definition["provider_options"].is_a?(Hash)
+            raise ArgumentError, "Tool provider_options must be a Hash"
+          end
+          Phronomy::Tool::Schema.new(definition.fetch("parameters_schema"))
+          Phronomy::Values::Immutable.validate_canonical_json!(definition, label: "Tool definition")
+          definition
+        end
+        names = normalized_tools.map { |tool| tool.fetch("name") }
+        raise ArgumentError, "duplicate Tool definition name" unless names.uniq == names
+        config = normalize_keys(model_config)
+        Phronomy::Values::Immutable.validate_canonical_json!(config, label: "LLM model configuration")
+        max = config["max_output_tokens"]
+        if !max.nil? && (!max.is_a?(Integer) || max <= 0)
+          raise ArgumentError, "max_output_tokens must be a positive Integer"
+        end
+        %w[model provider].each do |key|
+          value = config[key]
+          if !(value.nil? || (value.is_a?(String) && !value.empty?))
+            raise ArgumentError, "#{key} must be a non-empty String or nil"
+          end
+        end
+        %w[assume_model_exists cache_instructions].each do |key|
+          raise ArgumentError, "#{key} must be boolean or nil" unless [true, false, nil].include?(config[key])
+        end
+        temperature = config["temperature"]
+        if !(temperature.nil? || (temperature.is_a?(Numeric) && temperature.finite?))
+          raise ArgumentError, "temperature must be a finite number or nil"
+        end
+        @model_config = Phronomy::Values::Immutable.copy(config)
+        @system = system&.dup&.freeze
+        @message = message&.dup&.freeze
+        @messages = messages.dup.freeze
+        @tools = Phronomy::Values::Immutable.copy(normalized_tools)
+        freeze
+      end
+
+      private
+
+      def normalize_keys(value)
+        value.each_with_object({}) do |(key, child), result|
+          unless key.is_a?(String) || key.is_a?(Symbol)
+            raise ArgumentError, "LLM configuration/definition keys must be Strings or Symbols"
+          end
+          name = key.to_s
+          raise ArgumentError, "duplicate LLM configuration/definition key: #{name}" if result.key?(name)
+          result[name] = child
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/llm_adapter/response.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative "message"
+require_relative "token_usage"
+
+module Phronomy
+  module LLMAdapter
+    # Completed assistant turn. Tool requests do not authorize execution.
+    # @api public
+    class Response < Message
+      attr_reader :usage
+
+      # @api public
+      def initialize(content: nil, tool_calls: [], usage: Phronomy::LLMAdapter::TokenUsage.new, metadata: {}, role: :assistant)
+        raise ArgumentError, "LLM response must be an assistant message" unless role == :assistant || role == "assistant"
+        raise ArgumentError, "LLM usage must be LLMAdapter::TokenUsage" unless usage.is_a?(Phronomy::LLMAdapter::TokenUsage)
+        @usage = usage
+        super(role: :assistant, content: content, tool_calls: tool_calls, metadata: metadata)
+      end
+
+      # @api public
+      def self.from_h(value)
+        source = value.transform_keys(&:to_s)
+        new(role: source.fetch("role", "assistant"), content: source["content"],
+          tool_calls: source.fetch("tool_calls", []).map { |call| Phronomy::Tool::CallRequest.from_h(call) },
+          usage: Phronomy::LLMAdapter::TokenUsage.new(**source.fetch("usage", {}).transform_keys(&:to_sym)),
+          metadata: source.fetch("metadata", {}))
+      end
+
+      # @api public
+      def to_h
+        super.merge("usage" => usage.to_h.transform_keys(&:to_s))
+      end
+    end
+  end
+end

data/lib/phronomy/llm_adapter/stream_chunk.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module LLMAdapter
+    # Intermediate text notification; the final Response is authoritative.
+    # @api public
+    class StreamChunk
+      attr_reader :content
+
+      # @api public
+      def initialize(content:)
+        raise ArgumentError, "stream content must be a String or nil" unless content.nil? || content.is_a?(String)
+        @content = content&.dup&.freeze
+        freeze
+      end
+    end
+  end
+end

data/lib/phronomy/llm_adapter/token_usage.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module LLMAdapter
+    # Immutable usage counts. An omitted count remains nil; zero is a reported
+    # measurement. SDK field translation belongs to the backend.
+    # @api public
+    class TokenUsage
+      attr_reader :input, :output, :cached, :cache_creation
+
+      def initialize(input: nil, output: nil, cached: nil, cache_creation: nil)
+        [input, output, cached, cache_creation].each do |value|
+          if !(value.nil? || (value.is_a?(Integer) && value >= 0))
+            raise ArgumentError, "token usage must be non-negative Integers or nil"
+          end
+        end
+        @input = input
+        @output = output
+        @cached = cached
+        @cache_creation = cache_creation
+        freeze
+      end
+
+      # Returns a zero-valued TokenUsage suitable as an accumulator seed.
+      def self.zero
+        new(input: 0, output: 0, cached: 0, cache_creation: 0)
+      end
+
+      # Adds two TokenUsage instances. nil fields are treated as 0 so that
+      # partially-reported usage accumulates correctly.
+      # When other is nil, returns self unchanged.
+      def +(other)
+        return self if other.nil?
+
+        self.class.new(
+          input: _add(input, other.input),
+          output: _add(output, other.output),
+          cached: _add(cached, other.cached),
+          cache_creation: _add(cache_creation, other.cache_creation)
+        )
+      end
+
+      def ==(other)
+        other.is_a?(TokenUsage) &&
+          input == other.input &&
+          output == other.output &&
+          cached == other.cached &&
+          cache_creation == other.cache_creation
+      end
+
+      def to_h
+        {input: input, output: output, cached: cached, cache_creation: cache_creation}
+      end
+
+      private
+
+      def _add(a, b)
+        return nil if a.nil? && b.nil?
+
+        (a || 0) + (b || 0)
+      end
+    end
+  end
+end

data/lib/phronomy/llm_adapter/transport_error.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative "../common/error"
+
+module Phronomy
+  module LLMAdapter
+    class TransportError < Phronomy::Error; end
+  end
+end

data/lib/phronomy/llm_adapter.rb

@@ -1,22 +1,9 @@
 # frozen_string_literal: true
 
 module Phronomy
-  # Namespace for LLM call adapters.
-  #
-  # The public extension boundary is {LLMAdapter::Base#complete} and
-  # {LLMAdapter::Base#stream}. Those methods receive Phronomy's currently
-  # materialized chat/runtime object and perform the provider call. Phronomy owns
-  # the async/offload bridge around that synchronous contract.
-  #
-  # This SPI does not by itself make the complete input-materialization pipeline
-  # provider-neutral: the current Agent pipeline still materializes the canonical
-  # LLM input through RubyLLM-specific runtime objects before invoking the adapter.
-  #
-  # @example Configuring a custom adapter
-  #   Phronomy.configure do |c|
-  #     c.llm_adapter = MyCustomAdapter.new
-  #   end
-  #
+  # LLM domain operations and public request, response, usage and failure values.
+  # A backend implements Base's protected hooks. SDK objects remain inside the
+  # backend; AsyncClient executes the entire synchronous operation on a worker.
   # @api public
   module LLMAdapter
   end

data/lib/phronomy/llm_context_window/token_budget.rb

@@ -2,20 +2,19 @@
 
 module Phronomy
   module LlmContextWindow
-    # Immutable arithmetic value for one resolved model context budget.
-    # Model-registry lookup belongs to Agent::TokenBudgetResolver.
+    # Immutable input-budget arithmetic. RubyLLM owns model capabilities.
     class TokenBudget
-      attr_reader :context_window, :max_output_tokens
+      attr_reader :max_input_tokens
 
       # @api private
-      def initialize(context_window:, max_output_tokens:)
-        @context_window = Integer(context_window)
-        @max_output_tokens = Integer(max_output_tokens)
+      def initialize(max_input_tokens:)
+        @max_input_tokens = Integer(max_input_tokens)
+        raise ArgumentError, "max_input_tokens must be positive" unless @max_input_tokens.positive?
       end
 
       # @api private
       def effective_input_limit
-        [@context_window - @max_output_tokens, 0].max
+        @max_input_tokens
       end
 
       # @api private

data/lib/phronomy/multi_agent/admission_registry.rb

@@ -2,18 +2,25 @@
 
 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.
+    # Environment-local admission for one synchronous coordination call per owner
+    # (a Handoff main Agent or TeamCoordinator). This does not own durable runs
+    # or active-agent mutation; those remain in their existing domains.
+    # @api private
     class AdmissionRegistry
       def initialize
         @mutex = Mutex.new
         @cond = ConditionVariable.new
         @owners = {}
+        @draining = false
       end
 
       def admit!(coordinator)
         key = coordinator.object_id
         @mutex.synchronize do
+          if @draining
+            raise Phronomy::RuntimeShutdownError,
+              "Runtime is shutting down or failed; new Multi-Agent turns are not accepted"
+          end
           if @owners.key?(key)
             raise Phronomy::HandoffError,
               "a Multi-Agent turn is already active for this main Agent instance"
@@ -36,6 +43,12 @@ module Phronomy
         @mutex.synchronize { @owners.empty? }
       end
 
+      # Close admission atomically with respect to admit!, without waiting for
+      # admitted callers or calling back into Runtime. Repeated closure is safe.
+      def begin_draining
+        @mutex.synchronize { @draining = true }
+      end
+
       def wait_until_idle(deadline)
         @mutex.synchronize do
           until @owners.empty?

data/lib/phronomy/multi_agent/durable_subagent_coordinator.rb

@@ -1,127 +1,151 @@
 # frozen_string_literal: true
 
-require "securerandom"
+require "digest"
 
 module Phronomy
   module MultiAgent
-    # Agent-owned transactions reserve child work; TaskResult callbacks only wake observers.
+    # Owns slot reservations and import progress. The Agent participant stores
+    # only this binding's opaque state reference alongside its own transition.
     # @api private
     class DurableSubagentCoordinator
-      KEY = "multi_agent_coordination_ref"
+      BINDING_KEY = "phronomy.subagent"
+      attr_reader :persistence
 
-      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)
+      def initialize(agent_class:, persistence:)
+        @agent_class, @persistence = agent_class, persistence
+        @definitions = agent_class.registered_subagents
+      end
+
+      def binding
+        Phronomy::Agent::ExecutionExtensionState.new(binding_key: BINDING_KEY, binding_version: 1)
+      end
+
+      def guard_change(change, scope)
+        snapshot = state_for(change.extension)
+        ids = [change.agent_id] + snapshot.fetch("children").filter_map do |child|
+          child.fetch("agent_id") if persistence.agent_store.exist?(child.fetch("agent_id"))
         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
-          }
+        persistence.agent_store.guard_agents(scope, agent_ids: ids)
+      end
+
+      # The referenced content is immutable and is part of Agent's commit proof.
+      def change_evidence(change, scope)
+        persistence.agent_store.retained_references(agent_id: change.agent_id, scope: scope).map(&:to_h)
+      end
+
+      def commit(change)
+        persistence.coordinator.atomic do |scope|
+          guard_change(change, scope)
+          change.prepare_in(scope)
+          snapshot = state_for(change.extension)
+          children = snapshot.fetch("children").map(&:dup)
+          cancelled = snapshot["cancel_requested"] || change.cancel_requested ||
+            persistence.agent_store.cancellation_requested?(agent_id: change.agent_id, execution_id: change.execution_id, scope: scope)
+          children.each do |child|
+            observed = persistence.agent_store.observe_execution(agent_id: child.fetch("agent_id"), execution_id: child.fetch("execution_id"), scope: scope)
+            # This is import progress, not a replicated child execution state.
+            child["imported"] = true if observed.terminal? && change.kind == :dispatch && change.operations.empty?
+          end
+          change.operations.each do |operation|
+            entry = @definitions.find { |name, _| "dispatch_to_#{name}" == operation.name }
+            next unless entry
+            next if children.any? { |child| child.fetch("slot") == operation.invocation_id }
+            name, settings = entry
+            digest = Digest::SHA256.hexdigest(Phronomy::CanonicalJSON.dump(
+              ["phronomy-subagent-v1", change.agent_id, change.execution_id, operation.invocation_id]
+            ))
+            knowledge = settings.fetch(:inherit_knowledge) ? persistence.agent_store.knowledge_snapshot(agent_id: change.agent_id, scope: scope) : []
+            children << {"slot" => operation.invocation_id, "name" => name.to_s,
+                         "definition" => settings.fetch(:agent_class).agent_definition.transform_keys(&:to_s),
+                         "agent_id" => "subagent-#{digest}", "execution_id" => "subagent-execution-#{digest}",
+                         "input" => operation.arguments.fetch("input"), "durable_context" => change.durable_context,
+                         "knowledge" => knowledge.map { |item| {"content" => item.content, "metadata" => item.metadata} },
+                         "on_error" => settings.fetch(:on_error).to_s, "imported" => false}
+          end
+          unless children.empty?
+            persistence.agent_store.retain(Phronomy::Agent::Retention.new(agent_id: change.agent_id,
+              execution_id: change.execution_id, owner_key: "subagent:#{change.execution_id}"), scope: scope)
+          end
+          unresolved = children.any? do |child|
+            observed = persistence.agent_store.observe_execution(agent_id: child.fetch("agent_id"), execution_id: child.fetch("execution_id"), scope: scope)
+            observed.active? || (observed.absent? && !cancelled)
+          end
+          persistence.participate(scope) do |records|
+            ref = records.contents.put_json(snapshot.merge("children" => children, "cancel_requested" => !!cancelled))
+            state = Phronomy::Agent::ExecutionExtensionState.new(binding_key: BINDING_KEY, binding_version: 1, state_ref: ref)
+            change.commit_in(scope, state: state,
+              pending: change.kind == :terminal && unresolved && (change.cancel_requested || change.recovery_required))
+          end
         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 state_for(extension)
+        extension&.state_ref ? persistence.contents.fetch_json(extension.state_ref) : {"children" => [], "cancel_requested" => false}
       end
 
       def self.start(parent:, tool_invocation_id:, parent_execution_id:, config:)
-        runtime = Phronomy::Runtime.instance
         completion = Phronomy::TaskResult.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))
+        preparation = Phronomy::Execution.submit(on_full: :raise) do
+          store = parent.coordination_store
+          extension = parent.persistence.execution_extension(agent_id: parent.agent_id, execution_id: parent_execution_id, binding_key: BINDING_KEY)
+          raise Phronomy::ExecutionRehydrationRequiredError, "Missing subagent reservation state" unless extension&.state_ref
+          snapshot = store.contents.fetch_json(extension.state_ref)
           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")}"
+          settings = parent.class.registered_subagents.find { |name, _| name.to_s == child.fetch("name") }&.last
+          unless settings && settings.fetch(:agent_class).agent_definition.transform_keys(&:to_s) == child.fetch("definition")
+            raise Phronomy::ConfigurationError, "Registered child definition changed"
           end
-          klass = definition.fetch(:agent_class)
+          klass = settings.fetch(:agent_class)
           id = child.fetch("agent_id")
+          retention = Phronomy::Agent::Retention.new(agent_id: id, execution_id: child.fetch("execution_id"), owner_key: "subagent:#{parent_execution_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)
+            if parent.persistence.exist?(id)
+              agent = klass.load(id, persistence: parent.persistence, on_event: parent.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)
+              raise Phronomy::CancellationError, "Parent reservation was cancelled" if snapshot["cancel_requested"]
+              knowledge = child.fetch("knowledge").map { |item| Phronomy::Agent::KnowledgeItem.new(content: item.fetch("content"), metadata: item.fetch("metadata")) }
+              agent = klass.create(agent_id: id, persistence: parent.persistence, knowledge: knowledge,
+                retention: retention, on_event: parent.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]
+          raise Phronomy::ConfigurationError, "Child Persistence mismatch" unless agent.persistence.equal?(parent.persistence)
+          [child, agent, store]
         end
         preparation.on_complete do |prepared, failure|
           if failure
-            completion.fail(Phronomy::ExecutionRehydrationRequiredError.new("Child reservation requires recovery: #{failure.message}"))
+            completion.fail(failure.is_a?(Phronomy::CancellationError) ? failure : Phronomy::ExecutionRehydrationRequiredError.new("Child reservation requires recovery: #{failure.message}"))
             next
           end
-          child, agent, input, durable_context = prepared
+          child, agent, store = prepared
+          owner = {"kind" => "subagent", "parent_execution_id" => parent_execution_id,
+                   "parent_agent_id" => parent.agent_id, "slot" => tool_invocation_id}
           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|
+                          phronomy_admission: ReservedChildAdmission.new(persistence: store, owner: owner)}.compact
+          child_config[:durable_context] = child["durable_context"] if child["durable_context"]
+          reservation = Phronomy::Agent::ReservedExecution.new(agent_id: agent.agent_id, execution_id: child.fetch("execution_id"), correlation: owner)
+          agent.start_reserved_async(reservation: reservation, input: child.fetch("input"), config: child_config).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
+              completion.fail(error.is_a?(Phronomy::CancellationError) ? error : Phronomy::ExecutionRehydrationRequiredError.new("Child #{reservation.execution_id} is unfinished: #{error.message}"))
             elsif result[:error]
-              if child.fetch("on_error") == "skip"
+              if child.fetch("on_error") == "skip" && result[:status] != :cancelled
                 completion.complete(nil)
               else
-                completion.fail(Phronomy::Agent::RecoverySupport.error_from_failure(result[:error]))
+                observed = Phronomy::Agent::ExecutionObservation.from_result(result)
+                begin
+                  observed.value!
+                rescue => failure
+                  completion.fail(failure)
+                end
               end
             else
               completion.complete(result[:output])
             end
           end
         rescue => error
-          completion.fail(Phronomy::ExecutionRehydrationRequiredError.new("Child coordination requires recovery: #{error.message}"))
+          completion.fail(error)
         end
         completion
       rescue => error

data/lib/phronomy/multi_agent/execution_environment.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module MultiAgent
+    # Process-local connection selected by composition. MultiAgent owns the
+    # admission and Team identity rules; the environment connects their
+    # registries to shutdown and submits work to the originating executor.
+    # Environments and registries are never durable execution authority.
+    # @api private
+    class ExecutionEnvironment
+      class << self
+        def install_provider(provider)
+          raise ArgumentError, "MultiAgent execution provider must be callable" unless provider.respond_to?(:call)
+          @provider = provider
+        end
+
+        def current
+          @provider&.call || raise(Phronomy::ConfigurationError, "MultiAgent execution environment has not been configured")
+        end
+      end
+
+      def admissions = raise(NotImplementedError)
+      def ownership = raise(NotImplementedError)
+      def existing_ownership = raise(NotImplementedError)
+      def current? = raise(NotImplementedError)
+      def submit(**options, &operation) = raise(NotImplementedError)
+    end
+  end
+end

data/lib/phronomy/{agent → multi_agent}/handoff.rb

@@ -3,7 +3,7 @@
 require "digest"
 
 module Phronomy
-  module Agent
+  module MultiAgent
     # Application-defined semantic edge for transferring active responsibility
     # from one live Agent instance to another.
     class Handoff
@@ -19,7 +19,7 @@ module Phronomy
           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"
+          raise ArgumentError, "policy must be a Phronomy::MultiAgent::HandoffPolicy"
         end
 
         @source_agent = source_agent

data/lib/phronomy/{agent → multi_agent}/handoff_capability_factory.rb

@@ -1,9 +1,28 @@
 # frozen_string_literal: true
 
 module Phronomy
-  module Agent
+  module MultiAgent
     class HandoffCapabilityFactory
       Binding = Data.define(:handoff, :tool_class, :tool_name) do
+        def source_agent_id = handoff.source_agent.agent_id
+
+        def request(arguments:, llm_call_id:, tool_call_id:)
+          args = arguments.transform_keys(&:to_sym)
+          allowed = [:responsibility] + handoff.policy.selectable_categories.map { |category| :"include_#{category}" }
+          raise ArgumentError, "Unknown Handoff argument" unless (args.keys - allowed).empty?
+          selection = HandoffPolicy::CATEGORIES.to_h do |category|
+            value = if handoff.policy.selectable?(category)
+              args.fetch(:"include_#{category}") { handoff.policy.default_include?(category) }
+            else
+              handoff.policy.required?(category)
+            end
+            [category, value]
+          end
+          Phronomy::Agent::ControlRequest.new(target_agent_id: handoff.target_agent.agent_id,
+            responsibility: args.fetch(:responsibility), selection: selection,
+            llm_call_id: llm_call_id, tool_call_id: tool_call_id)
+        end
+
         def initialize(handoff:, tool_class:, tool_name:)
           super(handoff: handoff, tool_class: tool_class, tool_name: tool_name.to_s.freeze)
           freeze
@@ -16,7 +35,7 @@ module Phronomy
         description = handoff.description
         policy = handoff.policy
 
-        klass = Class.new(Phronomy::Agent::Context::Capability::Base) do
+        klass = Class.new(Phronomy::Tool::Base) do
           self.tool_name(tool_name)
           self.description(description)
           execution_mode :cooperative