phronomy 0.26.0 → 0.28.0

data/lib/phronomy/agent/{context_assembler.rb → context_preparation.rb}

@@ -2,29 +2,13 @@
 
 module Phronomy
   module Agent
-    class ContextAssembler
-      ASSEMBLY_POLICY_VERSION = 8
+    class ContextPreparation
       SEGMENT_ORIGIN_METADATA_KEY = "phronomy_origin"
       POLICY_ORIGIN_METADATA_KEY = "context_policy_origin"
       POLICY_ITEM_ID_METADATA_KEY = "context_policy_item_id"
-      SEMANTIC_CATEGORY_METADATA_KEY = "context_policy_semantic_category"
-      CONTENT_FORMAT_METADATA_KEY = "context_policy_content_format"
-      CONVERSATION_GROUP_ID_METADATA_KEY = "context_policy_conversation_group_id"
-      TRUSTED_HANDOFF_METADATA_KEYS = %w[
-        handoff_policy_category
-        handoff_provenance
-      ].freeze
-      HANDOFF_POLICY_CATEGORY_METADATA_KEY = "handoff_policy_category"
       BEFORE_LLM_INPUT_ORIGIN = "before_llm_input"
       HANDOFF_CONTEXT_ORIGIN = "handoff_context"
 
-      Prepared = Data.define(:input, :plan, :model_config, :call_sequence, :call_mode) do
-        def initialize(**values)
-          super
-          freeze
-        end
-      end
-
       def initialize(
         agent:,
         persistence:,
@@ -38,102 +22,51 @@ module Phronomy
         @candidate_resolver = candidate_resolver || ContextCandidateResolver.new(
           content_loader: method(:fetch_content)
         )
-        @input_builder = ContextPolicyInputBuilder.new(
+        @input_builder = Phronomy::Context::ContextPolicyInputBuilder.new(
           content_loader: method(:fetch_content)
         )
       end
 
       # Builds one immutable Policy input snapshot and executes Application Policy.
       # This method must run outside a Phronomy Persistence transaction.
-      def prepare_initial(input:, agent_root:, execution:, config: {}, patch: LLMInputPatch.empty)
+      def prepare_initial(input:, agent_root:, execution:, config: {}, patch: Phronomy::Context::LLMInputPatch.empty)
         projection = journal_projection(agent_root)
         model_cfg = effective_model_config(config, patch)
-        tool_set = ToolDefinitionSet.build(
-          @agent,
-          additional_tools: handoff_tool_classes(config)
-        )
+        tool_set = @agent.send(:tool_definition_set, additional_tools: handoff_tool_classes(config))
         system_text = build_system_text(input)
         hook_candidates = normalize_candidates(patch.segment_candidates)
         input_ref = execution.metadata.fetch("current_input_ref")
         current_input_content = @persistence.contents.fetch_text(input_ref)
         excluded = [execution.metadata["current_input_record_id"]].compact
-        handoff_context = config[:phronomy_handoff_context]
+        handoff_context = config[:phronomy_transfer_context]
 
-        instructions = []
-        unless system_text.to_s.empty?
-          instructions << ContextPolicyInput::InstructionItem.new(
-            id: "instruction:agent:#{execution.execution_id}:1",
-            kind: :instruction,
-            role: :system,
-            content: system_text.to_s,
-            content_format: :text,
-            estimated_tokens: estimate_value(system_text.to_s),
-            required: true,
-            provenance: ContextPolicyInput::Provenance.new(origin: :agent_configuration),
-            metadata: {}
-          )
-        end
-        if handoff_context
-          instructions << ContextPolicyInput::InstructionItem.new(
-            id: "instruction:handoff:#{execution.execution_id}:1",
-            kind: :handoff_responsibility,
-            role: :user,
-            content: handoff_context.responsibility.to_s,
-            content_format: :text,
-            estimated_tokens: estimate_value(handoff_context.responsibility.to_s),
-            required: true,
-            provenance: ContextPolicyInput::Provenance.new(origin: :handoff_context),
-            metadata: {SEGMENT_ORIGIN_METADATA_KEY => HANDOFF_CONTEXT_ORIGIN}
-          )
-        end
+        instructions = initial_instruction_items(
+          system_text,
+          handoff_context,
+          execution: execution
+        )
 
-        generation = agent_root.transcript_generation
-        eligible_working = Array(execution.working_records).select do |record|
-          record.context_candidate && record.context_generation == generation
-        end
-        candidates = @candidate_resolver.resolve(
-          prior_records: projection.context_records,
-          working_records: eligible_working,
+        candidates = resolve_record_candidates(
+          projection,
+          agent_root: agent_root,
+          execution: execution,
           excluded_record_ids: excluded
         )
-        candidates = merge_hook_candidates(
+        candidates = merge_context_candidates(
           candidates,
           hook_candidates,
+          handoff_context,
           agent_root: agent_root,
           execution: execution,
           call_sequence: 1
         )
-        candidates = merge_handoff_candidates(
-          candidates,
-          handoff_context,
+        current_input = current_input_item(
+          current_input_content,
+          input_ref: input_ref,
+          candidates: candidates,
+          agent_root: agent_root,
           execution: execution
         )
-        next_sequence = Array(candidates).filter_map(&:sequence).max.to_i + 1
-        current_input = ContextPolicyInput::ConversationItem.new(
-          id: "current-input:#{execution.execution_id}",
-          kind: :current_input,
-          role: :user,
-          content: current_input_content,
-          content_format: :text,
-          sequence: next_sequence,
-          estimated_tokens: estimate_value(current_input_content),
-          required: true,
-          provenance: ContextPolicyInput::Provenance.new(
-            origin: :working,
-            content_ref: input_ref,
-            record_id: execution.metadata["current_input_record_id"],
-            agent_id: agent_root.agent_id,
-            execution_id: execution.execution_id
-          ),
-          tool_call_id: nil,
-          tool_call_ids: [],
-          delivery: :ask_argument,
-          metadata: {
-            "source_agent_id" => agent_root.agent_id,
-            "source_execution_id" => execution.execution_id,
-            "handoff_policy_category" => "current_request"
-          }
-        )
 
         prepare(
           agent_root: agent_root,
@@ -157,44 +90,31 @@ module Phronomy
         agent_root:,
         execution:,
         config: {},
-        patch: LLMInputPatch.empty
+        patch: Phronomy::Context::LLMInputPatch.empty
       )
         projection = journal_projection(agent_root)
         model_cfg = effective_model_config(config, patch)
         hook_candidates = normalize_candidates(patch.segment_candidates)
-        handoff_context = config[:phronomy_handoff_context]
-        tool_set = ToolDefinitionSet.build(
-          @agent,
-          additional_tools: handoff_tool_classes(config)
-        )
+        handoff_context = config[:phronomy_transfer_context]
+        tool_set = @agent.send(:tool_definition_set, additional_tools: handoff_tool_classes(config))
 
-        instructions = base_manifest.segments.filter_map do |segment|
-          next unless retained_base_instruction?(segment)
-          instruction_item_from_manifest(segment)
-        end
+        instructions = retained_instruction_items(base_manifest)
 
-        generation = agent_root.transcript_generation
-        eligible_working = Array(execution.working_records).select do |record|
-          record.context_candidate && record.context_generation == generation
-        end
-        candidates = @candidate_resolver.resolve(
-          prior_records: projection.context_records,
-          working_records: eligible_working,
+        candidates = resolve_record_candidates(
+          projection,
+          agent_root: agent_root,
+          execution: execution,
           excluded_record_ids: []
         )
         call_sequence = execution.llm_calls.length + 1
-        candidates = merge_hook_candidates(
+        candidates = merge_context_candidates(
           candidates,
           hook_candidates,
+          handoff_context,
           agent_root: agent_root,
           execution: execution,
           call_sequence: call_sequence
         )
-        candidates = merge_handoff_candidates(
-          candidates,
-          handoff_context,
-          execution: execution
-        )
 
         prepare(
           agent_root: agent_root,
@@ -211,68 +131,113 @@ module Phronomy
       end
 
       # Validates and canonicalizes a previously prepared Policy decision.
-      # This method contains no ContextPolicy invocation and is safe to execute in
+      # This method contains no Phronomy::Context::ContextPolicy invocation and is safe to execute in
       # the short commit transaction after the caller revalidates durable revision.
-      def finalize(prepared, persistence: @persistence)
-        unless prepared.is_a?(Prepared)
-          raise ArgumentError, "ContextAssembler#finalize expected ContextAssembler::Prepared"
-        end
 
-        plan = ContextPlanValidator.new.validate!(input: prepared.input, plan: prepared.plan)
-        segments = []
-        plan.instruction.each do |item|
-          segments << segment_from_content_item(
-            item,
-            persistence: persistence,
-            additional_metadata: {SEMANTIC_CATEGORY_METADATA_KEY => "instruction"}
-          )
+      def initial_instruction_items(system_text, handoff_context, execution:)
+        instructions = []
+        unless system_text.to_s.empty?
+          instructions << agent_instruction_item(system_text, execution: execution)
         end
-        plan.knowledge.each do |item|
-          segments << segment_from_content_item(
-            item,
-            persistence: persistence,
-            additional_metadata: {SEMANTIC_CATEGORY_METADATA_KEY => "knowledge"}
-          )
+        if handoff_context
+          instructions << handoff_instruction_item(handoff_context, execution: execution)
         end
-        plan.conversation.each_with_index do |group, group_index|
-          group_metadata = {
-            SEMANTIC_CATEGORY_METADATA_KEY => "conversation",
-            CONVERSATION_GROUP_ID_METADATA_KEY =>
-              "conversation:#{prepared.call_sequence}:#{group_index}"
-          }
-          if tool_exchange_group?(group)
-            group_metadata[HANDOFF_POLICY_CATEGORY_METADATA_KEY] = "tool_exchanges"
-          end
+        instructions
+      end
 
-          group.each do |item|
-            segments << segment_from_content_item(
-              item,
-              persistence: persistence,
-              additional_metadata: group_metadata
-            )
-          end
+      def agent_instruction_item(system_text, execution:)
+        Phronomy::Context::ContextPolicyInput::InstructionItem.new(
+          id: "instruction:agent:#{execution.execution_id}:1",
+          kind: :instruction,
+          role: :system,
+          content: system_text.to_s,
+          content_format: :text,
+          estimated_tokens: estimate_value(system_text.to_s),
+          required: true,
+          provenance: Phronomy::Context::ContextPolicyInput::Provenance.new(origin: :agent_configuration),
+          metadata: {}
+        )
+      end
+
+      def handoff_instruction_item(handoff_context, execution:)
+        Phronomy::Context::ContextPolicyInput::InstructionItem.new(
+          id: "instruction:handoff:#{execution.execution_id}:1",
+          kind: :handoff_responsibility,
+          role: :user,
+          content: handoff_context.responsibility.to_s,
+          content_format: :text,
+          estimated_tokens: estimate_value(handoff_context.responsibility.to_s),
+          required: true,
+          provenance: Phronomy::Context::ContextPolicyInput::Provenance.new(origin: :handoff_context),
+          metadata: {SEGMENT_ORIGIN_METADATA_KEY => HANDOFF_CONTEXT_ORIGIN}
+        )
+      end
+
+      def retained_instruction_items(base_manifest)
+        base_manifest.segments.filter_map do |segment|
+          next unless retained_base_instruction?(segment)
+          instruction_item_from_manifest(segment)
         end
+      end
 
-        selected_tool_definitions = plan.tools.map(&:definition)
-        ContextParts::Validators::FinalBudgetValidator.new(
-          content_loader: lambda { |ref| fetch_content_from(persistence, ref) }
-        ).validate!(
-          token_budget: prepared.input.token_budget,
-          segments: segments,
-          extra_values: [selected_tool_definitions]
+      def resolve_record_candidates(projection, agent_root:, execution:, excluded_record_ids:)
+        generation = agent_root.transcript_generation
+        eligible_working = Array(execution.working_records).select do |record|
+          record.context_candidate && record.context_generation == generation
+        end
+        @candidate_resolver.resolve(
+          prior_records: projection.context_records,
+          working_records: eligible_working,
+          excluded_record_ids: excluded_record_ids
         )
+      end
 
-        store_manifest(
-          persistence: persistence,
-          call_sequence: prepared.call_sequence,
-          call_mode: prepared.call_mode,
-          segments: segments,
-          model_config_ref: persistence.contents.put_json(prepared.model_config),
-          tool_definitions_ref: persistence.contents.put_json(selected_tool_definitions)
+      def merge_context_candidates(
+        candidates, hook_candidates, handoff_context,
+        agent_root:, execution:, call_sequence:
+      )
+        candidates = merge_hook_candidates(
+          candidates,
+          hook_candidates,
+          agent_root: agent_root,
+          execution: execution,
+          call_sequence: call_sequence
+        )
+        merge_handoff_candidates(
+          candidates,
+          handoff_context,
+          execution: execution
         )
       end
 
-      private
+      def current_input_item(content, input_ref:, candidates:, agent_root:, execution:)
+        next_sequence = Array(candidates).filter_map(&:sequence).max.to_i + 1
+        Phronomy::Context::ContextPolicyInput::ConversationItem.new(
+          id: "current-input:#{execution.execution_id}",
+          kind: :current_input,
+          role: :user,
+          content: content,
+          content_format: :text,
+          sequence: next_sequence,
+          estimated_tokens: estimate_value(content),
+          required: true,
+          provenance: Phronomy::Context::ContextPolicyInput::Provenance.new(
+            origin: :working,
+            content_ref: input_ref,
+            record_id: execution.metadata["current_input_record_id"],
+            agent_id: agent_root.agent_id,
+            execution_id: execution.execution_id
+          ),
+          tool_call_id: nil,
+          tool_call_ids: [],
+          delivery: :ask_argument,
+          metadata: {
+            "source_agent_id" => agent_root.agent_id,
+            "source_execution_id" => execution.execution_id,
+            "handoff_policy_category" => "current_request"
+          }
+        )
+      end
 
       def prepare(
         agent_root:,
@@ -286,7 +251,7 @@ module Phronomy
         tools:,
         current_input:
       )
-        token_budget = TokenBudgetResolver.new(agent: @agent).resolve(model_config)
+        token_budget = Phronomy::Agent::Settings.current.llm_adapter.input_budget(model_config)
         policy_input = @input_builder.build(
           agent_id: agent_root.agent_id,
           execution_id: execution.execution_id,
@@ -306,38 +271,12 @@ module Phronomy
             "execution_revision" => execution.execution_revision
           }
         )
-        plan = invoke_policy(policy_input)
-        ContextPlanValidator.new.validate!(input: policy_input, plan: plan)
-        Prepared.new(
-          input: policy_input,
-          plan: plan,
-          model_config: model_config,
-          call_sequence: call_sequence,
-          call_mode: call_mode
+        Phronomy::Context::Assembly.new.prepare(
+          input: policy_input, policy: @policy,
+          adapter_identity: Phronomy::Agent::Settings.current.llm_adapter.identity
         )
       end
 
-      def invoke_policy(policy_input)
-        tracer = Phronomy.configuration.tracer
-        span = tracer.start_span(
-          "context_policy",
-          agent_id: policy_input.agent_id,
-          execution_id: policy_input.execution_id,
-          call_sequence: policy_input.call_sequence,
-          policy_class: @policy.class.name || @policy.class.to_s,
-          instruction_count: policy_input.instruction.length,
-          knowledge_count: policy_input.knowledge.length,
-          tool_count: policy_input.tools.length,
-          conversation_group_count: policy_input.conversation.length
-        )
-        result = @policy.call(policy_input)
-        tracer.finish_span(span)
-        result
-      rescue => error
-        tracer&.finish_span(span, error: error) if defined?(span) && span
-        raise
-      end
-
       def journal_projection(agent_root)
         if @journal_records
           JournalProjection.new(agent_root: agent_root, records: @journal_records)
@@ -360,7 +299,7 @@ module Phronomy
       def instruction_item_from_manifest(segment)
         origin = segment.metadata[POLICY_ORIGIN_METADATA_KEY] ||
           ((segment.category.to_sym == :handoff_responsibility) ? "handoff_context" : "agent_configuration")
-        ContextPolicyInput::InstructionItem.new(
+        Phronomy::Context::ContextPolicyInput::InstructionItem.new(
           id: segment.metadata[POLICY_ITEM_ID_METADATA_KEY] || "manifest-instruction:#{segment.position}",
           kind: segment.category,
           role: segment.role,
@@ -368,7 +307,7 @@ module Phronomy
           content_format: :text,
           estimated_tokens: estimate_value(fetch_content(segment.content_ref)),
           required: true,
-          provenance: ContextPolicyInput::Provenance.new(
+          provenance: Phronomy::Context::ContextPolicyInput::Provenance.new(
             origin: origin.to_sym,
             content_ref: segment.content_ref
           ),
@@ -379,91 +318,17 @@ module Phronomy
       def tool_items(tool_set)
         tool_set.definitions.map do |definition|
           name = definition.fetch("name")
-          ContextPolicyInput::ToolItem.new(
+          Phronomy::Context::ContextPolicyInput::ToolItem.new(
             id: "tool:#{name}",
             definition: definition,
             estimated_tokens: estimate_value(definition),
             required: false,
-            provenance: ContextPolicyInput::Provenance.new(origin: :agent_configuration),
+            provenance: Phronomy::Context::ContextPolicyInput::Provenance.new(origin: :agent_configuration),
             metadata: {}
           )
         end.freeze
       end
 
-      def store_manifest(
-        persistence:,
-        call_sequence:,
-        call_mode:,
-        segments:,
-        model_config_ref:,
-        tool_definitions_ref:
-      )
-        positioned = segments.each_with_index.map do |value, position|
-          LLMInputManifest::Segment.new(**value.merge(position: position))
-        end
-        manifest = LLMInputManifest.new(
-          call_sequence: call_sequence,
-          call_mode: call_mode,
-          segments: positioned,
-          model_config_ref: model_config_ref,
-          tool_definitions_ref: tool_definitions_ref,
-          assembly_policy_version: ASSEMBLY_POLICY_VERSION,
-          ruby_llm_version: defined?(RubyLLM::VERSION) ? RubyLLM::VERSION : nil,
-          adapter_name: Phronomy.configuration.llm_adapter.class.name
-        )
-        [manifest, persistence.contents.put_json(manifest.to_h)]
-      end
-
-      def segment_from_content_item(item, persistence:, additional_metadata: {})
-        content_ref = item.provenance.content_ref || store_item_content(item, persistence)
-        metadata = sanitized_item_metadata(item).merge(additional_metadata).merge(
-          CONTENT_FORMAT_METADATA_KEY => item.content_format.to_s,
-          POLICY_ITEM_ID_METADATA_KEY => item.id,
-          POLICY_ORIGIN_METADATA_KEY => item.provenance.origin.to_s,
-          "journal_record_id" => item.provenance.record_id,
-          "source_agent_id" => item.provenance.agent_id,
-          "source_execution_id" => item.provenance.execution_id,
-          "llm_call_id" => item.provenance.llm_call_id
-        ).compact
-
-        {
-          category: item.kind,
-          role: item.role,
-          content_ref: content_ref,
-          delivery: item.respond_to?(:delivery) ? item.delivery : :chat_message,
-          tool_call_id: item.respond_to?(:tool_call_id) ? item.tool_call_id : nil,
-          metadata: metadata
-        }
-      end
-
-      def sanitized_item_metadata(item)
-        raw = item.metadata.to_h.transform_keys(&:to_s)
-        # :working origin is Phronomy-controlled (from perform_initial_preparation),
-        # so handoff routing metadata on working records is equally trusted.
-        trusted_handoff = if item.provenance.origin == :handoff || item.provenance.origin == :working
-          raw.slice(*TRUSTED_HANDOFF_METADATA_KEYS)
-        else
-          {}
-        end
-
-        raw.except(*ContextPolicyInput::FRAMEWORK_METADATA_KEYS)
-          .merge(trusted_handoff)
-      end
-
-      def tool_exchange_group?(group)
-        Array(group).any? do |item|
-          item.kind == :assistant_message && !item.tool_call_ids.empty?
-        end && Array(group).any? { |item| item.kind == :tool_message }
-      end
-
-      def store_item_content(item, persistence)
-        if item.content_format == :json
-          persistence.contents.put_json(item.content)
-        else
-          persistence.contents.put_text(item.content.to_s)
-        end
-      end
-
       def effective_model_config(config, patch)
         apply_model_config_patch(model_config(config), patch.model_config_patch)
       end
@@ -474,15 +339,23 @@ module Phronomy
           "provider" => @agent.class.provider&.to_s,
           "temperature" => @agent.class.temperature,
           "max_output_tokens" => @agent.class.max_output_tokens,
-          "context_window" => @agent.class.context_window,
-          "cache_instructions" => !!@agent.class.cache_instructions,
-          "parallel_tool_execution" => !!Phronomy.configuration.parallel_tool_execution
+          "cache_instructions" => !!@agent.class.cache_instructions
         }.compact
       end
 
       def apply_model_config_patch(base, patch)
         return base unless patch
-        base.merge(patch.to_h.transform_keys(&:to_s)).compact
+        values = patch.to_h.transform_keys(&:to_s)
+        if values.key?("context_window")
+          raise Phronomy::ConfigurationError,
+            "context_window is model metadata; configure the LLM backend model metadata"
+        end
+        if values.key?("max_output_tokens") && !values["max_output_tokens"].nil?
+          cap = Integer(values["max_output_tokens"])
+          raise ArgumentError, "max_output_tokens must be positive" unless cap.positive?
+          values["max_output_tokens"] = cap
+        end
+        base.merge(values).compact
       end
 
       def normalize_candidates(candidates)
@@ -494,7 +367,7 @@ module Phronomy
           metadata = (hash[:metadata] || hash["metadata"] || {})
             .to_h
             .transform_keys(&:to_s)
-          validate_application_metadata!(metadata, source: "LLMInputPatch segment candidate")
+          validate_application_metadata!(metadata, source: "Phronomy::Context::LLMInputPatch segment candidate")
           {
             content: content,
             category: category,
@@ -505,7 +378,7 @@ module Phronomy
       end
 
       def validate_application_metadata!(metadata, source:)
-        conflicts = metadata.keys.map(&:to_s) & ContextPolicyInput::FRAMEWORK_METADATA_KEYS
+        conflicts = metadata.keys.map(&:to_s) & Phronomy::Context::ContextPolicyInput::FRAMEWORK_METADATA_KEYS
         return if conflicts.empty?
 
         raise ArgumentError,
@@ -527,7 +400,7 @@ module Phronomy
             "source_kind" => "hook",
             "content_format" => content.is_a?(String) ? "text" : "json"
           )
-          Selection::Candidate.new(
+          Phronomy::Context::Candidate.new(
             candidate_id: "hook:#{execution.execution_id}:#{call_sequence}:#{index}",
             source_kind: :hook,
             category: hook.fetch(:category),
@@ -539,7 +412,7 @@ module Phronomy
             llm_call_id: nil,
             tool_call_id: nil,
             sequence: next_sequence + index + 1,
-            constraint: Selection::Constraint.selectable(origin: :context_policy),
+            constraint: Phronomy::Context::Constraint.selectable(origin: :context_policy),
             priority: 0,
             metadata: metadata
           )
@@ -552,8 +425,8 @@ module Phronomy
       def merge_handoff_candidates(candidates, handoff_context, execution:)
         return Array(candidates).freeze unless handoff_context
 
-        unless handoff_context.is_a?(Phronomy::Agent::HandoffContext)
-          raise ArgumentError, "phronomy_handoff_context must be a HandoffContext"
+        unless handoff_context.is_a?(Phronomy::Agent::TransferContext)
+          raise ArgumentError, "phronomy_transfer_context must be a TransferContext"
         end
 
         next_sequence = Array(candidates).filter_map(&:sequence).max.to_i
@@ -572,7 +445,7 @@ module Phronomy
             "handoff_provenance" => item.provenance.to_h
           )
 
-          Selection::Candidate.new(
+          Phronomy::Context::Candidate.new(
             candidate_id: "handoff:#{execution.execution_id}:#{index}:#{item.provenance.origin_record_id || item.provenance.origin_tool_call_id || index}",
             source_kind: :handoff,
             category: item.candidate_category,
@@ -584,7 +457,7 @@ module Phronomy
             llm_call_id: item.provenance.origin_llm_call_id,
             tool_call_id: item.tool_call_id,
             sequence: next_sequence + index + 1,
-            constraint: Selection::Constraint.selectable(origin: :handoff_context),
+            constraint: Phronomy::Context::Constraint.selectable(origin: :handoff_context),
             priority: 50,
             metadata: metadata
           )
@@ -600,7 +473,7 @@ module Phronomy
       end
 
       def handoff_tool_classes(config)
-        Array(config[:phronomy_handoff_bindings]).map(&:tool_class).freeze
+        Array(config[:phronomy_control_bindings]).map(&:tool_class).freeze
       end
 
       def estimate_value(value)
@@ -609,13 +482,9 @@ module Phronomy
       end
 
       def fetch_content(ref)
-        fetch_content_from(@persistence, ref)
-      end
-
-      def fetch_content_from(persistence, ref)
-        persistence.contents.fetch_text(ref)
+        @persistence.contents.fetch_text(ref)
       rescue
-        persistence.contents.fetch(ref)
+        @persistence.contents.fetch(ref)
       end
 
       def build_system_text(input)

data/lib/phronomy/agent/control_request.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    # Value returned by a control capability after its domain policy is applied.
+    # Agent validates exclusivity and Source ownership before accepting it.
+    # @api public
+    ControlRequest = Data.define(:target_agent_id, :responsibility, :selection, :llm_call_id, :tool_call_id) do
+      def initialize(target_agent_id:, responsibility:, selection:, llm_call_id: nil, tool_call_id: nil)
+        raise ArgumentError, "target_agent_id is required" if target_agent_id.to_s.empty?
+        raise ArgumentError, "responsibility is required" if responsibility.to_s.strip.empty?
+        normalized = selection.to_h.transform_keys(&:to_sym)
+        unless normalized.values.all? { |value| value == true || value == false }
+          raise ArgumentError, "context selection values must be boolean"
+        end
+        super(target_agent_id: target_agent_id.to_s.freeze, responsibility: responsibility.to_s.strip.freeze,
+              selection: normalized.freeze, llm_call_id: llm_call_id&.to_s&.freeze, tool_call_id: tool_call_id&.to_s&.freeze)
+      end
+    end
+  end
+end