phronomy 0.22.0 → 0.23.0

data/lib/phronomy/agent/shared_state.rb

@@ -4,6 +4,15 @@ module Phronomy
   module Agent
     # Implements peer coordination through a shared KnowledgeStore.
     class SharedState
+      # Semantic revision of the framework-owned SharedState instrumentation
+      # applied on top of one specific researcher definition revision.
+      #
+      # The generated definition ID below already includes the wrapped
+      # researcher's definition ID/version. Increment this value only when the
+      # semantics of SharedState's injected coordination capabilities change.
+      INSTRUMENTATION_DEFINITION_VERSION = 1
+      private_constant :INSTRUMENTATION_DEFINITION_VERSION
+
       class KnowledgeStore
         def initialize
           @findings = []
@@ -168,7 +177,35 @@ module Phronomy
         definitions[read_tool] = nil
         definitions[write_tool] = nil
 
-        Class.new(researcher_class) { tools(definitions) }
+        # The anonymous subclass has a different effective Agent definition from the
+        # configured researcher because SharedState adds LLM-visible coordination
+        # Tools. D04 therefore requires a distinct semantic definition identity
+        # instead of reusing the researcher's exact definition revision.
+        #
+        # This is a framework-private generated lineage. It is derived from the
+        # wrapped researcher's *definition revision*, while its own version tracks the
+        # semantic revision of the SharedState instrumentation itself. This keeps the
+        # application's definition-version namespace independent from framework
+        # instrumentation.
+        instrumented_def = instrumented_definition_for(researcher_class)
+        Class.new(researcher_class) do
+          agent_definition(
+            id: instrumented_def.fetch(:id),
+            version: instrumented_def.fetch(:version)
+          )
+          tools(definitions)
+        end
+      end
+
+      def instrumented_definition_for(researcher_class)
+        parent_def = researcher_class.agent_definition
+        parent_id = parent_def.fetch(:id)
+        parent_version = parent_def.fetch(:version)
+
+        {
+          id: "Phronomy::Agent::SharedState::Instrumented/#{parent_id}@#{parent_version}".freeze,
+          version: INSTRUMENTATION_DEFINITION_VERSION
+        }.freeze
       end
 
       def build_prompt(

data/lib/phronomy/agent/tool_approval_request.rb

@@ -45,6 +45,20 @@ module Phronomy
           freeze
         end
 
+        def self.from_h(hash)
+          values = hash.to_h { |key, value| [key.to_s, value] }
+          new(
+            tool_invocation_id: values.fetch("tool_invocation_id"),
+            tool_call_id: values["tool_call_id"],
+            tool_name: values.fetch("tool_name"),
+            arguments: values.fetch("arguments", {}),
+            facts: values.fetch("facts", {}),
+            reason: values["reason"],
+            origin: values.fetch("origin", "local"),
+            metadata: values.fetch("metadata", {})
+          )
+        end
+
         def to_h
           {
             tool_invocation_id: @tool_invocation_id,
@@ -74,12 +88,23 @@ module Phronomy
         end
       end
 
-      attr_reader :id, :agent_invocation_id, :items, :created_at
+      attr_reader :id, :execution_id, :items, :created_at
+
+      def self.from_h(hash)
+        source = hash.to_h { |key, value| [key.to_s, value] }
+        items = Array(source.fetch("items")).map { |item| Item.from_h(item) }
+        new(
+          execution_id: source.fetch("execution_id"),
+          items: items,
+          id: source.fetch("id"),
+          created_at: Time.iso8601(source.fetch("created_at"))
+        )
+      end
 
       def self.build(agent_invocation)
         pending = agent_invocation.tool_invocations.select(&:awaiting_approval?)
         new(
-          agent_invocation_id: agent_invocation.id,
+          execution_id: agent_invocation.execution_id,
           items: pending.map { |invocation| build_item(invocation) }
         )
       end
@@ -98,11 +123,14 @@ module Phronomy
       end
       private_class_method :build_item
 
-      def initialize(agent_invocation_id:, items:, id: SecureRandom.uuid, created_at: Time.now.utc)
+      def initialize(execution_id:, items:, id: SecureRandom.uuid, created_at: Time.now.utc)
         raise ArgumentError, "ToolApprovalRequest requires at least one item" if items.empty?
+        if execution_id.nil? || execution_id.to_s.empty?
+          raise ArgumentError, "ToolApprovalRequest requires execution_id"
+        end
 
         @id = id.to_s.freeze
-        @agent_invocation_id = agent_invocation_id.to_s.freeze
+        @execution_id = execution_id.to_s.freeze
         @items = items.dup.freeze
         @created_at = created_at
         freeze
@@ -111,7 +139,7 @@ module Phronomy
       def to_h
         {
           id: @id,
-          agent_invocation_id: @agent_invocation_id,
+          execution_id: @execution_id,
           items: @items.map(&:to_h),
           created_at: @created_at.iso8601
         }

data/lib/phronomy/agent/tool_definition_set.rb

@@ -5,8 +5,8 @@ module Phronomy
     class ToolDefinitionSet
       attr_reader :runtime_tools, :definitions
 
-      def self.build(agent)
-        runtime_tools = (agent.class.tools + agent.send(:_handoff_tools)).freeze
+      def self.build(agent, additional_tools: [])
+        runtime_tools = (agent.class.tools + Array(additional_tools)).freeze
         definitions = runtime_tools.map do |tool_class|
           prepared = agent.send(:prepare_tool_class, tool_class)
           tool = prepared.is_a?(Class) ? prepared.new : prepared
@@ -46,10 +46,56 @@ module Phronomy
       end
 
       def initialize(runtime_tools:, definitions:)
-        @runtime_tools = runtime_tools
+        @runtime_tools = Array(runtime_tools).freeze
         @definitions = Immutable.copy(definitions)
+        validate_unique_names!
         freeze
       end
+
+      def select_definitions(expected_definitions)
+        expected = Immutable.copy(Array(expected_definitions))
+        current_by_name = definitions.each_with_index.to_h do |definition, index|
+          [definition.fetch("name"), [definition, runtime_tools.fetch(index)]]
+        end
+        seen = {}
+        selected_tools = []
+        selected_definitions = []
+
+        expected.each do |definition|
+          name = definition.fetch("name").to_s
+          raise ArgumentError, "duplicate selected Tool definition: #{name}" if seen[name]
+          seen[name] = true
+
+          current_definition, runtime_tool = current_by_name.fetch(name) do
+            raise Phronomy::ConfigurationError,
+              "ContextPolicy selected Tool not present in current Agent configuration: #{name}"
+          end
+          unless Phronomy::CanonicalJSON.dump(current_definition) ==
+              Phronomy::CanonicalJSON.dump(definition)
+            raise Phronomy::ConfigurationError,
+              "Agent Tool definition changed after ContextPolicy selection: #{name}"
+          end
+
+          selected_tools << runtime_tool
+          selected_definitions << current_definition
+        end
+
+        self.class.new(
+          runtime_tools: selected_tools,
+          definitions: selected_definitions
+        )
+      end
+
+      private
+
+      def validate_unique_names!
+        names = definitions.map { |definition| definition.fetch("name").to_s }
+        duplicates = names.group_by(&:itself).select { |_name, values| values.length > 1 }.keys
+        return if duplicates.empty?
+
+        raise Phronomy::ConfigurationError,
+          "duplicate effective Tool definition name(s): #{duplicates.inspect}"
+      end
     end
   end
 end