phronomy 0.16.0 → 0.18.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,38 @@ 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."
+          execution_mode :cooperative
 
           define_method(:execute) { store.read_all.to_json }
         end
@@ -250,7 +152,8 @@ 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."
+          execution_mode :cooperative
           param :content, type: :string, desc: "The finding to record"
 
           define_method(:execute) do |content:|
@@ -259,16 +162,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 +190,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

@@ -43,9 +43,8 @@ module Phronomy
             "set max_output_tokens or Phronomy.configuration.default_output_reserve"
         end
 
-        # ContextAssembler passes the actual mandatory Manifest content to
-        # ContextSelector. Reserving context_overhead here would count system
-        # instructions and tool definitions a second time.
+        # 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
@@ -62,7 +61,9 @@ module Phronomy
       end
 
       def stringify_keys(hash)
-        hash.to_h.each_with_object({}) { |(key, value), result| result[key.to_s] = value }
+        hash.to_h.each_with_object({}) do |(key, value), result|
+          result[key.to_s] = value
+        end
       end
     end
   end

data/lib/phronomy/agent/tool_executor.rb

@@ -2,90 +2,48 @@
 
 module Phronomy
   module Agent
-    # Centralises Tool execution routing based on execution_mode.
+    # Routes Tool work according to the Tool execution contract.
     #
-    # Tool-specific timeout and retry belong to the Tool implementation or its
-    # underlying client. This executor only chooses the Phronomy execution
-    # resource and propagates cooperative cancellation.
-    # @api private
+    # :cooperative Tool calls execute inline and must return quickly. call_async
+    # wraps their result in an already-settled Task and never consumes an
+    # OffloadPool worker.
+    #
+    # :offloaded Tool calls route synchronous work through OffloadPool. Phronomy
+    # does not distinguish whether the reason is blocking I/O, CPU-bound work, or
+    # another long synchronous operation.
     module ToolExecutor
-      WARNED_MODES = Set.new
-      WARNED_MODES_MUTEX = Mutex.new
-      private_constant :WARNED_MODES, :WARNED_MODES_MUTEX
-
-      # Agent-owned execution boundary. Only a ToolInvocation that has consumed
-      # authorization may enter this method.
-      def self.call_invocation_async(
-        tool_invocation:,
-        cancellation_token: nil,
-        config: {},
-        runtime: Phronomy::Runtime.instance
-      )
-        unless tool_invocation.dispatchable?
-          raise Phronomy::ToolError,
-            "ToolInvocation #{tool_invocation.id} is not authorized for dispatch"
-        end
-
-        call_async(
-          tool: tool_invocation.tool,
-          args: tool_invocation.arguments,
-          cancellation_token: cancellation_token,
-          config: config,
-          runtime: runtime
-        )
-      end
-
-      # Low-level Tool API used by direct Tool#call_async callers. Agent execution
-      # must use .call_invocation_async so authorization cannot be bypassed.
-      #
-      # +config+ remains available for invocation metadata, but Phronomy does not
-      # interpret it as a Tool timeout or retry policy.
       def self.call_async(
         tool:,
         args:,
         cancellation_token: nil,
         config: {},
-        runtime: Phronomy::Runtime.instance
+        runtime: nil,
+        on_full: :raise
       )
-        ct = cancellation_token
         mode = tool.class.execution_mode
 
-        if mode == :cpu_bound || mode == :external_process
-          warn_key = [tool.class.name, mode]
-          newly_warned = WARNED_MODES_MUTEX.synchronize { WARNED_MODES.add?(warn_key) }
-          if newly_warned
-            message = if mode == :cpu_bound
-              "[Phronomy] Tool #{tool.class.name} declares execution_mode :cpu_bound, " \
-                "which has no dedicated executor. Falling back to blocking_io " \
-                "(BlockingAdapterPool). Use :blocking_io explicitly to suppress this warning."
-            else
-              "[Phronomy] Tool #{tool.class.name} declares execution_mode :external_process, " \
-                "which has no dedicated process manager. Falling back to blocking_io " \
-                "(BlockingAdapterPool)."
-            end
-            if Phronomy.configuration.logger
-              Phronomy.configuration.logger.warn(message)
-            else
-              warn message
-            end
+        case mode
+        when :cooperative
+          task = Phronomy::Task.deferred(name: "tool-#{tool.name}")
+          begin
+            task.complete(
+              tool.call(args, cancellation_token: cancellation_token)
+            )
+          rescue => error
+            task.fail(error)
           end
-          mode = :blocking_io
-        end
-
-        pool = begin
-          runtime&.blocking_io
-        rescue
-          nil
-        end
-
-        if mode == :cooperative || pool.nil?
-          runtime.spawn(name: "tool-#{tool.class.name.to_s.split("::").last}") do
-            tool.call(args, cancellation_token: ct)
+          task
+        when :offloaded
+          runtime ||= Phronomy::Runtime.instance
+          runtime.offload.submit(
+            cancellation_token: cancellation_token,
+            on_full: on_full
+          ) do
+            tool.call(args, cancellation_token: cancellation_token)
           end
         else
-          pool.submit(cancellation_token: ct) do
-            tool.call(args, cancellation_token: ct)
-          end
+          raise Phronomy::ConfigurationError,
+            "unknown Tool execution_mode: #{mode.inspect}"
         end
       end
     end