phronomy 0.15.1 → 0.17.0

data/lib/phronomy/agent/shared_state.rb

@@ -2,79 +2,24 @@
 
 module Phronomy
   module Agent
-    # Implements the "Shared state" coordination pattern (Anthropic blog, Pattern 5).
-    #
-    # @see https://claude.com/blog/multi-agent-coordination-patterns
-    #
-    # Multiple peer agents collaborate through a shared {KnowledgeStore}.
-    # There is no central coordinator. Each agent reads the store, acts on what it
-    # finds, and writes new findings back. Later agents in a cycle immediately see
-    # findings written by earlier agents in the same cycle.
-    #
-    # Two tools are automatically injected into every member agent at runtime:
-    # - +read_store+    — returns all current findings as a JSON string
-    # - +write_finding+ — appends a Hash finding to the store
-    #
-    # Use +member+ to register agents and optionally provide per-agent coordination
-    # instructions. Use +coordination+ to define the team-level protocol that all
-    # members receive instead of the built-in default guide.
-    #
-    # @example Basic usage with per-agent instructions
-    #   class CodeReviewTeam < Phronomy::Agent::SharedState
-    #     member StructureAnalyst
-    #     member SecurityAuditor, instruction: "Focus on authentication and injection risks."
-    #     member QualityReviewer,  instruction: "Flag methods longer than 10 lines."
-    #     max_cycles  3
-    #     aggregate   { |store| { findings: store.read_all, total: store.size } }
-    #   end
-    #
-    #   result = CodeReviewTeam.new.invoke("Review the files in ./src")
-    #   # => { output: { findings: [...], total: N }, cycles: 3, terminated_by: :max_cycles }
-    #
-    # @example With custom team-level coordination protocol
-    #   class ResearchTeam < Phronomy::Agent::SharedState
-    #     coordination <<~TEXT
-    #       Shared store tools: read_store (no params), write_finding(content:).
-    #       Workflow: read first, then write one finding per insight.
-    #     TEXT
-    #     member LiteratureAgent
-    #     member IndustryAgent
-    #     max_cycles  10
-    #     terminate_when { |store| store.size >= 20 }
-    #   end
+    # Implements peer coordination through a shared KnowledgeStore.
     class SharedState
-      # Thread-safe (serialised by sequential execution) knowledge store shared
-      # across all researcher agents within a single {SharedState#invoke} call.
-      #
-      # Each finding is stored as a Hash with the keys:
-      #   :agent   — Symbol derived from the researcher class name
-      #   :content — String written by the researcher
-      #   :cycle   — Integer cycle number in which the finding was recorded
       class KnowledgeStore
         def initialize
           @findings = []
         end
 
-        # Returns a shallow copy of all findings in insertion order.
-        # @return [Array<Hash>]
         # @api public
         def read_all
           @findings.dup
         end
 
-        # Appends a new finding to the store.
-        # @param agent   [Symbol]  researcher identifier
-        # @param content [String]  the finding text
-        # @param cycle   [Integer] the current cycle number
-        # @return [nil]
         # @api public
         def write(agent:, content:, cycle:)
           @findings << {agent: agent, content: content, cycle: cycle}
           nil
         end
 
-        # Returns the number of findings recorded so far.
-        # @return [Integer]
         # @api public
         def size
           @findings.size
@@ -82,96 +27,45 @@ module Phronomy
       end
 
       class << self
-        # Registers a member agent class that will collaborate via the shared store.
-        # Members are invoked sequentially within each cycle in declaration order.
-        #
-        # @param klass [Class] an Agent::Base subclass
-        # @param instruction [String, nil] optional per-agent coordination instruction
-        #   appended to the team coordination text in this agent's prompt
         # @api public
         def member(klass, instruction: nil)
           @members ||= []
           @members << {klass: klass, instruction: instruction}
         end
 
-        # Backward-compatible alias. Registers each class as a member without a
-        # per-agent instruction. Prefer {.member} for new code.
-        #
-        # @param classes [Array<Class>] Agent::Base subclasses
-        # @api public
-        def researchers(*classes)
-          classes.flatten.each { |klass| member(klass) }
-        end
-
-        # Defines the team-level coordination protocol text injected into every
-        # member's prompt. When omitted the built-in default guide is used, which
-        # explains +read_store+ / +write_finding+ usage and enforces the standard
-        # workflow. Override this when you need a different protocol or tone.
-        #
-        # @param text [String, nil] the coordination instructions
         # @api public
         def coordination(text = nil)
           text ? @coordination = text : @coordination
         end
 
-        # Sets the maximum number of cycles to run.
-        # At least one of +max_cycles+ or +timeout+ must be configured.
-        #
-        # @param value [Integer, nil]
         # @api public
         def max_cycles(value = nil)
           value ? @max_cycles = Integer(value) : @max_cycles
         end
 
-        # Sets the maximum wall-clock seconds for the entire invocation.
-        # At least one of +max_cycles+ or +timeout+ must be configured.
-        #
-        # @param value [Numeric, nil]
         # @api public
         def timeout(value = nil)
           value ? @timeout = value.to_f : @timeout
         end
 
-        # Registers an optional convergence block. Evaluated after each completed
-        # cycle; when it returns +true+ the loop terminates early.
-        #
-        # @yield [KnowledgeStore] receives the store; return +true+ to stop
         # @api public
         def terminate_when(&block)
           block ? @terminate_when = block : @terminate_when
         end
 
-        # Defines how the final store is converted into the +:output+ of the result.
-        # When omitted, +store.read_all+ is used as-is.
-        #
-        # @yield [KnowledgeStore] receives the final store; return value becomes +:output+
         # @api public
         def aggregate(&block)
           block ? @aggregator = block : @aggregator
         end
 
-        # @!visibility private
         def _members = Array(@members)
-        # @!visibility private — derives class list from _members for backward compat
-        def _researchers = _members.map { |m| m[:klass] }
-        # @!visibility private
         def _coordination = @coordination
-        # @!visibility private
         def _max_cycles = @max_cycles
-        # @!visibility private
         def _timeout = @timeout
-        # @!visibility private
         def _terminate_when = @terminate_when
-        # @!visibility private
         def _aggregator = @aggregator
       end
 
-      # Runs the shared-state coordination loop.
-      #
-      # @param input  [String] the seed question or task description
-      # @param config [Hash]   reserved for future use
-      # @return [Hash] +:output+, +:cycles+, +:terminated_by+
-      # @raise [ArgumentError] when neither +max_cycles+ nor +timeout+ is configured
       # @api public
       def invoke(input, config: {})
         validate_termination!
@@ -181,12 +75,17 @@ module Phronomy
         deadline = self.class._timeout ? Time.now + self.class._timeout : nil
         terminated_by = :max_cycles
         completed_cycles = 0
-
         cycle_limit = max_cycles || Float::INFINITY
 
         (1..cycle_limit).each do |cycle|
           self.class._members.each do |member_config|
-            invoke_researcher(member_config[:klass], store, cycle, input, member_config[:instruction])
+            invoke_researcher(
+              member_config[:klass],
+              store,
+              cycle,
+              input,
+              member_config[:instruction]
+            )
           end
           completed_cycles = cycle
 
@@ -199,8 +98,6 @@ module Phronomy
             terminated_by = :timeout
             break
           end
-
-          terminated_by = :max_cycles
         end
 
         output = if self.class._aggregator
@@ -216,33 +113,37 @@ module Phronomy
 
       def validate_termination!
         return if self.class._max_cycles || self.class._timeout
+
         raise ArgumentError,
           "max_cycles or timeout must be configured before invoking SharedState"
       end
 
-      # Invokes a single member agent for one cycle.
-      # Builds an anonymous subclass with +read_store+ and +write_finding+ injected,
-      # then calls +invoke+ with a prompt that includes the coordination guide,
-      # any per-agent instruction, and the current store contents.
-      def invoke_researcher(researcher_class, store, cycle, original_input, per_agent_instruction = nil)
+      def invoke_researcher(
+        researcher_class,
+        store,
+        cycle,
+        original_input,
+        per_agent_instruction = nil
+      )
         instrumented = build_instrumented_researcher(researcher_class, store, cycle)
         extra_tools = researcher_class.tools
-        prompt = build_prompt(original_input, store, cycle,
+        prompt = build_prompt(
+          original_input,
+          store,
+          cycle,
           extra_tools: extra_tools,
-          per_agent_instruction: per_agent_instruction)
+          per_agent_instruction: per_agent_instruction
+        )
         instrumented.new.invoke(prompt)
       end
 
-      # Builds an anonymous subclass of +researcher_class+ with two store tools
-      # injected. The tools close over the +store+ instance so that writes and
-      # reads are reflected in the live store.
       def build_instrumented_researcher(researcher_class, store, cycle)
         agent_key = researcher_class.name&.to_sym || researcher_class.object_id.to_s.to_sym
 
         read_tool = Class.new(Phronomy::Agent::Context::Capability::Base) do
           tool_name "read_store"
           description "Read all current findings from the shared knowledge store. " \
-                      "Call this to see what other researchers have discovered."
+            "Call this to see what other researchers have discovered."
 
           define_method(:execute) { store.read_all.to_json }
         end
@@ -250,7 +151,7 @@ module Phronomy
         write_tool = Class.new(Phronomy::Agent::Context::Capability::Base) do
           tool_name "write_finding"
           description "Record a new finding into the shared knowledge store so " \
-                      "that other researchers can build on your discovery."
+            "that other researchers can build on your discovery."
           param :content, type: :string, desc: "The finding to record"
 
           define_method(:execute) do |content:|
@@ -259,16 +160,22 @@ module Phronomy
           end
         end
 
-        parent_tools = researcher_class.tools
-        Class.new(researcher_class) { tools(*parent_tools, read_tool, write_tool) }
+        definitions = researcher_class.tools.to_h do |tool_class|
+          [tool_class, researcher_class.tool_aliases[tool_class]]
+        end
+        definitions[read_tool] = nil
+        definitions[write_tool] = nil
+
+        Class.new(researcher_class) { tools(definitions) }
       end
 
-      # Builds the invocation prompt for a member agent.
-      # Uses the team-level coordination text when defined via {.coordination},
-      # otherwise falls back to the built-in default guide. Appends any per-agent
-      # instruction after the coordination text. Subsequent cycles also include
-      # the current store contents so agents can build on prior findings.
-      def build_prompt(original_input, store, cycle, extra_tools: [], per_agent_instruction: nil)
+      def build_prompt(
+        original_input,
+        store,
+        cycle,
+        extra_tools: [],
+        per_agent_instruction: nil
+      )
         guide = self.class._coordination || default_coordination_guide(extra_tools)
 
         prompt_parts = [guide]
@@ -281,20 +188,21 @@ module Phronomy
         return base if store.size == 0
 
         findings_text = store.read_all
-          .map { |f| "- [#{f[:agent]} / cycle #{f[:cycle]}] #{f[:content]}" }
+          .map { |finding|
+            "- [#{finding[:agent]} / cycle #{finding[:cycle]}] #{finding[:content]}"
+          }
           .join("\n")
 
         "#{header}\n\nTask: #{original_input}\n\nFindings so far:\n#{findings_text}"
       end
 
-      # Builds the default tool-usage guide for member agents.
-      # Describes +read_store+ / +write_finding+ and the required workflow.
-      # When extra_tools are present, lists their names so the agent knows
-      # what additional tools are available.
       def default_coordination_guide(extra_tools)
         extra_line = if extra_tools.any?
-          tool_names = extra_tools.map { |t| t.respond_to?(:tool_name) ? t.tool_name : t.name.to_s }.join(", ")
-          "  You also have access to additional tools (#{tool_names}) — use them to gather information before writing findings.\n"
+          tool_names = extra_tools.map do |tool|
+            tool.respond_to?(:tool_name) ? tool.tool_name : tool.name.to_s
+          end.join(", ")
+          "  You also have access to additional tools (#{tool_names}) — " \
+            "use them to gather information before writing findings.\n"
         else
           ""
         end

data/lib/phronomy/agent/token_budget_resolver.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    # Resolves a TokenBudget from the effective model configuration that will
+    # actually be materialized for one LLM call.
+    class TokenBudgetResolver
+      def initialize(agent:)
+        @agent = agent
+      end
+
+      def resolve(model_config)
+        config = stringify_keys(model_config)
+        model_name = config["model"]
+        explicit_window = integer_or_nil(config["context_window"])
+        explicit_reserve = integer_or_nil(config["max_output_tokens"])
+
+        if explicit_window
+          reserve = explicit_reserve || configured_default_reserve
+          return build_budget(explicit_window, reserve, model_name)
+        end
+
+        return nil unless model_name
+
+        model = RubyLLM.models.find(model_name)
+        return nil unless model
+
+        context_window = model.context_window.to_i
+        registry_max = model.max_output_tokens.to_i
+        reserve = explicit_reserve || configured_default_reserve
+        reserve ||= registry_max if registry_max.positive? && registry_max < context_window
+        build_budget(context_window, reserve, model_name)
+      rescue RubyLLM::ModelNotFoundError
+        nil
+      end
+
+      private
+
+      def build_budget(context_window, reserve, model_name)
+        unless reserve&.positive? && reserve < context_window
+          raise Phronomy::InvalidContextBudgetConfigurationError,
+            "Cannot determine a valid output reserve for model #{model_name.inspect}; " \
+            "set max_output_tokens or Phronomy.configuration.default_output_reserve"
+        end
+
+        # Mandatory Manifest content is accounted separately by ContextAssembler
+        # and the final budget validator. TokenBudget reserves output capacity only.
+        Phronomy::LlmContextWindow::TokenBudget.new(
+          context_window: context_window,
+          max_output_tokens: reserve
+        )
+      end
+
+      def configured_default_reserve
+        integer_or_nil(Phronomy.configuration.default_output_reserve)
+      end
+
+      def integer_or_nil(value)
+        return nil if value.nil?
+        Integer(value)
+      end
+
+      def stringify_keys(hash)
+        hash.to_h.each_with_object({}) do |(key, value), result|
+          result[key.to_s] = value
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/agent/tool_call_intercepted.rb

@@ -2,18 +2,25 @@
 
 module Phronomy
   module Agent
-    # Raised by the Agent-owned RubyLLM ToolCall interceptor before execution.
+    # Normal control-transfer signal raised before RubyLLM executes a Tool Call.
+    #
+    # RubyLLM >= 1.15 guarantees that the complete assistant message has already
+    # been added to Chat#messages before before_tool_call runs. Keeping that
+    # message here allows Phronomy to persist the complete Provider outcome even
+    # though the RubyLLM call itself unwinds through this exception.
     # @api private
     class ToolCallIntercepted < StandardError
-      attr_reader :tool_calls
+      attr_reader :tool_calls, :assistant_message, :assistant_outcome, :llm_call_id
 
-      def initialize(tool_calls)
+      def initialize(tool_calls, assistant_message: nil, assistant_outcome: nil, llm_call_id: nil)
         @tool_calls = Array(tool_calls).freeze
+        @assistant_message = assistant_message
+        @assistant_outcome = assistant_outcome || ProviderCallOutcome.capture(assistant_message)
+        @llm_call_id = llm_call_id&.to_s&.freeze
         names = @tool_calls.map(&:name).join(", ")
         super("Tool call intercepted: #{names}")
       end
 
-      # Convenience accessor for callers that only support one ToolCall.
       def tool_call
         @tool_calls.first
       end

data/lib/phronomy/agent/tool_definition_set.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    class ToolDefinitionSet
+      attr_reader :runtime_tools, :definitions
+
+      def self.build(agent)
+        runtime_tools = (agent.class.tools + agent.send(:_handoff_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
+          {
+            "name" => tool.name.to_s,
+            "description" => tool.description.to_s,
+            "parameters_schema" => normalize(
+              tool.respond_to?(:parameters_schema) ? tool.parameters_schema : {}
+            ),
+            "provider_options" => normalize(
+              tool.respond_to?(:provider_options) ? tool.provider_options : {}
+            )
+          }
+        end.freeze
+        new(runtime_tools: runtime_tools, definitions: definitions)
+      end
+
+      def self.normalize(value)
+        case value
+        when Hash
+          value.to_h { |key, child| [key.to_s, normalize(child)] }
+        when Array
+          value.map { |child| normalize(child) }
+        when Symbol
+          value.to_s
+        when String, Integer, Float, TrueClass, FalseClass, NilClass
+          value
+        else
+          if value.respond_to?(:to_json_schema)
+            normalize(value.to_json_schema)
+          elsif value.respond_to?(:to_h)
+            normalize(value.to_h)
+          else
+            raise ArgumentError, "unsupported tool definition value: #{value.class}"
+          end
+        end
+      end
+
+      def initialize(runtime_tools:, definitions:)
+        @runtime_tools = runtime_tools
+        @definitions = Immutable.copy(definitions)
+        freeze
+      end
+    end
+  end
+end