phronomy 0.7.1 → 0.9.0

data/lib/phronomy/llm_context_window/assembler.rb

@@ -0,0 +1,191 @@
+# frozen_string_literal: true
+
+require "cgi"
+
+module Phronomy
+  module LlmContextWindow
+    # Assembler collects all four context regions and produces the final
+    # {system:, messages:, tool_classes:} hash consumed by Agent::Base.
+    #
+    # Regions:
+    #   1. Instruction  — system prompt text set via #add_instruction
+    #   2. Capability   — tool classes registered via #add_capability
+    #   3. Knowledge    — external facts injected via #add_knowledge (generates XML tags)
+    #   4. Conversation — historical messages added via #add_messages
+    #
+    # Token budgeting:
+    #   When a budget is given, conversation messages are trimmed from oldest to
+    #   newest until they fit. Capability token cost is estimated and deducted
+    #   from the budget before conversation trimming so the reserve is accurate.
+    #   Knowledge chunks are always included in full (they are assumed to be
+    #   pre-screened by the caller). When no budget is given all messages are
+    #   passed through unchanged.
+    #
+    # @example
+    #   assembler = Phronomy::LlmContextWindow::Assembler.new(budget: budget)
+    #   assembler.add_instruction("You are a helpful assistant.")
+    #   assembler.add_knowledge("The user lives in Tokyo.", type: :entity, trusted: false)
+    #   assembler.add_messages(manager.load(thread_id: "t1", query: user_input))
+    #   context = assembler.build
+    #   # => { system: "You are ...\n<context ...>...</context>", messages: [...] }
+    class Assembler
+      # Builds a single XML context tag string.
+      # Exposed as a class method so callers (e.g. Agent::Base) can build
+      # static knowledge XML tags independently of an Assembler instance.
+      #
+      # @param text    [String]
+      # @param type    [Symbol, String]
+      # @param trusted [Boolean]
+      # @return [String]
+      # @api private
+      # mutant:disable - text.to_str and plain text (no to_s) are genuine equivalents when text is a String; type.to_str is genuine equivalent when type is a String
+      def self.xml_tag(text, type:, trusted: false)
+        "<context type=\"#{CGI.escapeHTML(type.to_s)}\" trusted=\"#{trusted}\">\n#{CGI.escapeHTML(text.to_s)}\n</context>"
+      end
+
+      # @param budget [Phronomy::LlmContextWindow::TokenBudget, nil]
+      #   when nil no token trimming is performed
+      # @api private
+      # mutant:disable - @instruction = nil deletion is a genuine equivalent (uninitialized Ruby instance variables return nil)
+      def initialize(budget: nil)
+        @budget = budget
+        @instruction = nil
+        @tool_classes = []
+        @knowledge_chunks = []
+        @messages = []
+      end
+
+      # Register tool classes (Region 2).
+      # Estimates their token cost and deducts it from the budget so that
+      # conversation trimming accounts for tool definition overhead.
+      #
+      # @param tool_classes [Array<Class, Object>] tool classes or instances
+      # @return [self]
+      # @api private
+      def add_capability(tool_classes)
+        @tool_classes = Array(tool_classes)
+        self
+      end
+
+      # Set the system instruction text (Region 1).
+      # Calling this multiple times replaces the previous value.
+      #
+      # @param text [String]
+      # @return [self]
+      # @api private
+      # mutant:disable - text.to_str and plain text (no .to_s) are genuine equivalents when callers always pass a String
+      def add_instruction(text)
+        @instruction = text.to_s
+        self
+      end
+
+      # Append a knowledge chunk (Region 3).
+      # The chunk is wrapped in an XML context tag automatically.
+      #
+      # @param text    [String]
+      # @param type    [Symbol, String]  semantic label for the context tag (e.g. :entity, :rag, :static)
+      # @param trusted [Boolean]         false (default) indicates externally sourced data
+      # @param source  [String, nil]     optional source label (e.g. filename); included in the
+      #   XML tag so the LLM can produce grounded citations. Omitted when nil.
+      # @return [self]
+      # @api private
+      # mutant:disable - {text:} (shorthand, no .to_s) and text.to_str are genuine equivalents when text is a String; {type:} shorthand is genuine equivalent because xml_context_tag always calls .to_s on chunk[:type]
+      def add_knowledge(text, type:, trusted: false, source: nil)
+        @knowledge_chunks << {text: text.to_s, type: type.to_s, trusted: trusted, source: source}
+        self
+      end
+
+      # Set conversation messages (Region 4). Replaces any previously set messages.
+      #
+      # @param messages [Array] message-like objects with #role and #content
+      # @return [self]
+      # @api private
+      # mutant:disable - @messages = messages (no Array()) is a genuine equivalent when callers always pass an Array
+      def add_messages(messages)
+        @messages = Array(messages)
+        self
+      end
+
+      # Returns the number of tokens available for conversation messages after
+      # accounting for instruction, knowledge, and capability overhead.
+      # Returns +nil+ when no budget is configured.
+      #
+      # @return [Integer, nil]
+      # @api private
+      def available_for_messages
+        return nil unless @budget
+        knowledge_text = @knowledge_chunks.map { |c| xml_context_tag(c) }.join("\n\n")
+        system_parts = [@instruction, knowledge_text.empty? ? nil : knowledge_text].compact
+        system_text = system_parts.join("\n\n")
+        used = TokenEstimator.estimate(system_text) + estimate_capability_tokens
+        @budget.available(used: used)
+      end
+
+      # Assemble the context.
+      #
+      # @return [Hash{Symbol => Object}]
+      #   :system      [String, nil]  combined system prompt (instruction + knowledge XML tags)
+      #   :messages    [Array]        conversation messages, trimmed to budget if set
+      #   :tool_classes [Array]       tool classes/instances to register with the chat
+      # @api private
+      # Raises {Phronomy::ContextLengthError} when a budget is set and the
+      # conversation messages do not fit within the remaining token allowance.
+      # No automatic trimming is performed — callers must pre-process messages
+      # (e.g. via Agent::Base#trim_messages or #compact_messages) before
+      # passing them to the Assembler.
+      #
+      # mutant:disable - multiple genuine equivalent mutations: map{}.join("\n\n") → map{} is genuine; `unless knowledge_text.empty?` vs ternary is genuine; `{ system: unless system_text.empty? }` vs ternary is genuine; `messages:` shorthand vs `messages: messages` is genuine
+      def build
+        knowledge_text = @knowledge_chunks.map { |c| xml_context_tag(c) }.join("\n\n")
+        system_parts = [@instruction, knowledge_text.empty? ? nil : knowledge_text].compact
+        system_text = system_parts.join("\n\n")
+
+        if @budget && @messages.any?
+          capability_tokens = estimate_capability_tokens
+          used = TokenEstimator.estimate(system_text) + capability_tokens
+          remaining = @budget.available(used: used)
+          msg_tokens = @messages.sum { |m| TokenEstimator.estimate(m.content.to_s) }
+          if msg_tokens > remaining
+            raise Phronomy::ContextLengthError,
+              "Context exceeds token budget: messages require #{msg_tokens} tokens but " \
+              "only #{remaining} available (context_window=#{@budget.context_window}, " \
+              "used_by_system=#{used}). Override build_context to trim or compact messages."
+          end
+        end
+
+        {
+          system: system_text.empty? ? nil : system_text,
+          messages: @messages,
+          tool_classes: @tool_classes
+        }
+      end
+
+      private
+
+      # Estimates the token cost of all registered tool classes.
+      # Uses each tool's description and parameter names as a proxy for its
+      # JSON Schema size. This is a deliberate simplification — exact token
+      # counts require provider-specific schema serialization which lives in
+      # RubyLLM. The estimate errs on the side of being slightly conservative
+      # so that the conversation budget is not over-allocated.
+      def estimate_capability_tokens
+        @tool_classes.sum do |tc|
+          # Instantiated tool objects (e.g. Phronomy::Tools::Mcp instances) may not be a Class.
+          next 0 unless tc.is_a?(Class) && tc.respond_to?(:description)
+
+          text = [tc.description.to_s]
+          if tc.respond_to?(:parameters)
+            tc.parameters.each_key { |k| text << k.to_s }
+          end
+          TokenEstimator.estimate(text.join(" "))
+        end
+      end
+
+      # mutant:disable - multiple genuine equivalent mutations: chunk.fetch(key) vs chunk[key] (key always present); chunk[:text] no .to_s / .to_str are genuine (stored as String); chunk[:type] no .to_s / .to_str are genuine (stored as String); chunk[:source] no .to_s / .to_str are genuine (truthy branch, always String); src_attr chunk.fetch(:source) is genuine (source key always present)
+      def xml_context_tag(chunk)
+        src_attr = chunk[:source] ? " source=\"#{CGI.escapeHTML(chunk[:source].to_s)}\"" : ""
+        "<context type=\"#{CGI.escapeHTML(chunk[:type].to_s)}\"#{src_attr} trusted=\"#{chunk[:trusted]}\">\n#{CGI.escapeHTML(chunk[:text].to_s)}\n</context>"
+      end
+    end
+  end
+end

data/lib/phronomy/{context → llm_context_window}/context_version_cache.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Phronomy
-  module Context
+  module LlmContextWindow
     # Caches the assembled static system prompt text keyed by a SHA-256
     # fingerprint of the agent's instructions + static knowledge content.
     # Each instance is owned by one thread (stored in +Thread.current+).

data/lib/phronomy/{context → llm_context_window}/token_budget.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Phronomy
-  module Context
+  module LlmContextWindow
     # Raised when a model name is not found in the RubyLLM model registry and
     # no explicit context_window was provided.
     class UnknownModelError < Phronomy::Error; end
@@ -17,16 +17,16 @@ module Phronomy
     #   └─ effective_input_limit  (available for memory + knowledge)
     #
     # @example Auto-derive from RubyLLM model registry
-    #   budget = Phronomy::Context::TokenBudget.new(model: "claude-3-5-sonnet-20241022")
+    #   budget = Phronomy::LlmContextWindow::TokenBudget.new(model: "claude-3-5-sonnet-20241022")
     #
     # @example Explicit values (useful for local / unknown models)
-    #   budget = Phronomy::Context::TokenBudget.new(
+    #   budget = Phronomy::LlmContextWindow::TokenBudget.new(
     #     context_window:    32_768,
     #     max_output_tokens: 4_096
     #   )
     #
     # @example With overhead for instructions + tool definitions
-    #   budget = Phronomy::Context::TokenBudget.new(
+    #   budget = Phronomy::LlmContextWindow::TokenBudget.new(
     #     model:    "gpt-4o",
     #     overhead: 800
     #   )
@@ -46,6 +46,7 @@ module Phronomy
       #                                         and model is given, uses max_output_tokens
       # @param overhead          [Integer]      tokens reserved for instructions/tools
       # @api private
+      # mutant:disable - multiple genuine equivalent mutations: overhead/context_window/max_output_tokens .to_i vs .to_int vs Integer() vs omitted are equivalent for Integer inputs; (max_output_tokens||0).to_i vs (max_output_tokens).to_i and (||nil).to_i are genuine because nil.to_i==0; overhead:nil default is genuine because nil.to_i==0
       def initialize(model: nil, context_window: nil, max_output_tokens: nil, overhead: 0)
         @overhead = overhead.to_i
 
@@ -76,12 +77,14 @@ module Phronomy
       # @param used [Integer] tokens already committed (e.g. from knowledge injection)
       # @return [Integer] remaining tokens (always >= 0)
       # @api private
+      # mutant:disable - used.to_i vs used vs used.to_int vs Integer(used) are genuine equivalents when used is an Integer; used:nil default is genuine because nil.to_i==0==default 0
       def available(used: 0)
         [effective_input_limit - used.to_i, 0].max
       end
 
       private
 
+      # mutant:disable - raise(UnknownModelError) and raise(UnknownModelError,nil) and raise(UnknownModelError,"Model '#{nil}' not found") in both branches are genuine equivalents (spec checks exception class only, not message text)
       def lookup_model!(model_name)
         found = RubyLLM.models.find(model_name)
         raise UnknownModelError, "Model '#{model_name}' not found in RubyLLM registry" unless found

data/lib/phronomy/{context → llm_context_window}/token_estimator.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Phronomy
-  module Context
+  module LlmContextWindow
     # Central, stateless token estimation utility.
     #
     # All token counting in the framework passes through this module so that the
@@ -21,10 +21,10 @@ module Phronomy
     # @example Use tiktoken_ruby for accurate GPT token counts
     #   require "tiktoken_ruby"
     #   enc = Tiktoken.encoding_for_model("gpt-4o")
-    #   Phronomy::Context::TokenEstimator.tokenizer = ->(text) { enc.encode(text).length }
+    #   Phronomy::LlmContextWindow::TokenEstimator.tokenizer = ->(text) { enc.encode(text).length }
     #
     # @example Reset to built-in heuristic
-    #   Phronomy::Context::TokenEstimator.tokenizer = nil
+    #   Phronomy::LlmContextWindow::TokenEstimator.tokenizer = nil
     module TokenEstimator
       @tokenizer = nil
       @tokenizer_mutex = Mutex.new

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

@@ -3,16 +3,16 @@
 require "securerandom"
 
 module Phronomy
-  module Agent
+  module MultiAgent
     # Represents a transfer edge from one agent to another.
-    # Creates an anonymous Phronomy::Tool::Base subclass that the source agent
+    # Creates an anonymous Phronomy::Agent::Context::Capability::Base subclass that the source agent
     # exposes to the LLM as a +transfer_to_<name>+ function.
     # The tool's execute method returns a sentinel string that Runner uses to
     # detect which target agent to route to next.
     #
     # @example
     #   billing = BillingAgent.new
-    #   handoff = Phronomy::Agent::Handoff.new(target_agent: billing)
+    #   handoff = Phronomy::MultiAgent::Handoff.new(target_agent: billing)
     #   tool_class = handoff.to_tool_class
     class Handoff
       # Prefix embedded in tool results so Runner can detect handoffs.
@@ -32,14 +32,14 @@ module Phronomy
         @description = description || "Transfer the conversation to #{klass_name}."
       end
 
-      # Builds an anonymous Phronomy::Tool::Base subclass for this handoff.
-      # @return [Class<Phronomy::Tool::Base>]
+      # Builds an anonymous Phronomy::Agent::Context::Capability::Base subclass for this handoff.
+      # @return [Class<Phronomy::Agent::Context::Capability::Base>]
       # @api public
       def to_tool_class
         sentinel_value = sentinel
         tn = tool_name
         desc = description
-        Class.new(Phronomy::Tool::Base) do
+        Class.new(Phronomy::Agent::Context::Capability::Base) do
           tool_name tn
           description desc
           define_method(:execute) { sentinel_value }

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

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Phronomy
-  module Agent
+  module MultiAgent
     # Base class for orchestrator agents that coordinate multiple subagents.
     # Implements the Orchestrator-Subagent multi-agent coordination pattern
     # (Anthropic blog, Pattern 2).
@@ -16,7 +16,7 @@ module Phronomy
     # - +fan_out+ for parallel invocation of the same agent across multiple inputs.
     #
     # @example Declarative DSL
-    #   class ResearchOrchestrator < Phronomy::Agent::Orchestrator
+    #   class ResearchOrchestrator < Phronomy::MultiAgent::Orchestrator
     #     model "gpt-4o"
     #     instructions "You coordinate research tasks."
     #     subagent :searcher,   SearchAgent
@@ -26,7 +26,7 @@ module Phronomy
     #   result = ResearchOrchestrator.new.invoke("Research the latest AI news.")
     #
     # @example Programmatic parallel dispatch
-    #   class MyOrchestrator < Phronomy::Agent::Orchestrator
+    #   class MyOrchestrator < Phronomy::MultiAgent::Orchestrator
     #     model "gpt-4o"
     #     instructions "Dispatch tasks in parallel."
     #
@@ -41,7 +41,7 @@ module Phronomy
     #
     # @example Fan-out (same agent, multiple inputs)
     #   results = fan_out(agent: TranslationAgent, inputs: ["Hello", "World"])
-    class Orchestrator < Base
+    class Orchestrator < Agent::Base
       # Declares a named subagent and registers it as a tool accessible to the
       # LLM during an +invoke+ call.
       #
@@ -57,7 +57,7 @@ module Phronomy
       #   proceed
       # @api public
       def self.subagent(name, agent_class, on_error: :raise)
-        tool_class = Class.new(Phronomy::Tool::Base) do
+        tool_class = Class.new(Phronomy::Agent::Context::Capability::Base) do
           tool_name "dispatch_to_#{name}"
           description "Dispatch work to the #{name} subagent (#{agent_class.name})"
           param :input, type: :string, desc: "The task or question for the subagent"
@@ -142,7 +142,7 @@ module Phronomy
       #   nil means wait indefinitely. When the deadline is exceeded,
       #   {Phronomy::TimeoutError} is raised and all surviving tasks are cancelled
       #   cooperatively.
-      # @param cancellation_token [Phronomy::CancellationToken, nil] when provided, the
+      # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil] when provided, the
       #   token is merged into each task's config (unless the task already sets one) so
       #   that every child agent checks it before making LLM calls.
       # @param invocation_context [Phronomy::InvocationContext, nil] when provided,
@@ -313,7 +313,7 @@ module Phronomy
         end
 
         if timeout
-          deadline = Phronomy::Deadline.in(timeout)
+          deadline = Phronomy::Concurrency::Deadline.in(timeout)
           spawned.each { |t| t.join([deadline.remaining_seconds, 0].max) }
 
           alive = spawned.select(&:alive?)

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

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Phronomy
-  module Agent
+  module MultiAgent
     # RubyLLM::Chat subclass that executes multiple tool calls concurrently.
     #
     # When the LLM returns more than one tool call in a single response, each
@@ -25,7 +25,7 @@ module Phronomy
     # @api private
     class ParallelToolChat < RubyLLM::Chat
       # @param max_parallel_tools [Integer] maximum simultaneous tool executions
-      # @param cancellation_token [Phronomy::CancellationToken, nil] token observed before each batch
+      # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil] token observed before each batch
       # @param opts [Hash] remaining kwargs forwarded to RubyLLM::Chat
       # @api private
       def initialize(max_parallel_tools: 10, cancellation_token: nil, **opts)
@@ -95,7 +95,7 @@ module Phronomy
               }}
             end
 
-            awaitable = Phronomy::ToolExecutor.call_async(
+            awaitable = Phronomy::Agent::ToolExecutor.call_async(
               tool: tool,
               args: tc.arguments,
               cancellation_token: ct
@@ -138,7 +138,7 @@ module Phronomy
           }
         end
 
-        Phronomy::ToolExecutor.call_async(
+        Phronomy::Agent::ToolExecutor.call_async(
           tool: tool,
           args: tool_call.arguments,
           cancellation_token: @cancellation_token

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

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Phronomy
-  module Agent
+  module MultiAgent
     # Implements the "Agent teams" coordination pattern (Anthropic blog, Pattern 3).
     #
     # @see https://claude.com/blog/multi-agent-coordination-patterns
@@ -24,7 +24,7 @@ module Phronomy
     # +invoke+ call, so the LLM retains context across multiple task assignments.
     #
     # @example Basic usage
-    #   class MigrationTeam < Phronomy::Agent::TeamCoordinator
+    #   class MigrationTeam < Phronomy::MultiAgent::TeamCoordinator
     #     coordinator_model        "claude-3-5-sonnet-20241022"
     #     coordinator_instructions <<~INST
     #       Analyze the request and enqueue one migration task per service.
@@ -265,7 +265,7 @@ module Phronomy
 
       # Builds the +enqueue_task+ tool. Each call appends a task Hash to task_queue.
       def build_enqueue_tool(task_queue)
-        Class.new(Phronomy::Tool::Base) do
+        Class.new(Phronomy::Agent::Context::Capability::Base) do
           tool_name "enqueue_task"
           description "Add a task to the worker queue."
           param :description, type: :string, desc: "What the worker agent should do"
@@ -282,7 +282,7 @@ module Phronomy
       # Builds the +finalize+ tool. Signals to the coordinator LLM that all tasks
       # have been enqueued; returns a confirmation string.
       def build_finalize_tool(task_queue)
-        Class.new(Phronomy::Tool::Base) do
+        Class.new(Phronomy::Agent::Context::Capability::Base) do
           tool_name "finalize"
           description "Signal that task generation is complete. Call this after all tasks have been enqueued."
           param :summary, type: :string, desc: "Brief summary of what was enqueued", required: false

data/lib/phronomy/runtime/runtime_metrics.rb

@@ -90,7 +90,6 @@ module Phronomy
             active_agent_tasks: active[:agent].to_i,
             active_tool_tasks: active[:tool].to_i,
             active_workflow_tasks: active[:workflow].to_i,
-            active_rag_tasks: active[:rag].to_i,
             active_llm_tasks: active[:llm].to_i,
             task_wait_time_p50_ms: _percentile(wait, 50),
             task_wait_time_p95_ms: _percentile(wait, 95),

data/lib/phronomy/runtime.rb

@@ -8,8 +8,6 @@ require_relative "runtime/timer_queue"
 require_relative "runtime/scheduler_timer_adapter"
 require_relative "runtime/task_registry"
 require_relative "runtime/runtime_metrics"
-require_relative "runtime/gate_registry"
-require_relative "runtime/pool_registry"
 require_relative "runtime/timer_service"
 
 module Phronomy
@@ -99,6 +97,23 @@ module Phronomy
       !Task.current.nil?
     end
 
+    # Executes +block+ and returns +[result, elapsed_ms]+ where +elapsed_ms+
+    # is the wall-clock duration in milliseconds (Integer, rounded).
+    #
+    # Isolates all direct references to +Process.clock_gettime+ /
+    # +Process::CLOCK_MONOTONIC+ in one place so that callers stay at the
+    # framework abstraction level.
+    #
+    # @yield block to time
+    # @return [Array(Object, Integer)] +[block_return_value, elapsed_ms]+
+    # @api private
+    def self.measure_ms
+      t0 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      result = yield
+      elapsed_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - t0) * 1000).round
+      [result, elapsed_ms]
+    end
+
     # The scheduler backing this runtime instance.
     # @return [Scheduler]
     attr_reader :scheduler
@@ -109,8 +124,8 @@ module Phronomy
       @scheduler = scheduler
       @task_registry = TaskRegistry.new
       @metrics = RuntimeMetrics.new
-      @gate_registry = GateRegistry.new
-      @pool_registry = PoolRegistry.new
+      @gate_registry = Phronomy::Concurrency::GateRegistry.new
+      @pool_registry = Phronomy::Concurrency::PoolRegistry.new
       @timer_service = TimerService.new(scheduler)
     end
 
@@ -120,7 +135,7 @@ module Phronomy
     # is first accessed; subsequent calls return the cached gate.  To change the
     # cap at runtime, call {#reset_gate} first.
     #
-    # @param name [:agent, :tool, :workflow, :llm, :rag, :vector] resource name
+    # @param name [:agent, :tool, :workflow, :llm, :vector] resource name
     # @return [ConcurrencyGate]
     # @api private
     def gate(name)
@@ -264,7 +279,6 @@ module Phronomy
     # | `active_agent_tasks`      | currently running agent spawns |
     # | `active_tool_tasks`       | currently running tool spawns |
     # | `active_workflow_tasks`   | currently running workflow spawns |
-    # | `active_rag_tasks`        | currently running RAG fetches |
     # | `active_llm_tasks`        | currently running LLM calls |
     # | `task_wait_time_p50_ms`   | p50 spawn-to-start latency (ms) |
     # | `task_wait_time_p95_ms`   | p95 spawn-to-start latency (ms) |

data/lib/phronomy/task_group.rb

@@ -108,7 +108,7 @@ module Phronomy
     # @param tasks [Array<Task>]
     # @return [Array]
     def _await_all_cooperative(tasks)
-      completion_q = AsyncQueue.new
+      completion_q = Phronomy::Concurrency::AsyncQueue.new
       tasks.each_with_index do |task, idx|
         task.on_complete do |value, error|
           completion_q.push({index: idx, value: value, error: error})

data/lib/phronomy/tool.rb

@@ -1,9 +1,8 @@
 # frozen_string_literal: true
 
-require_relative "tool/base"
-require_relative "tool/mcp_tool"
-require_relative "tool/agent_tool"
-
+# This file is intentionally empty.
+# Tool definitions have moved to Phronomy::Agent::Context::Capability.
+# See lib/phronomy/agent/context/capability/.
 module Phronomy
   module Tool
   end

data/lib/phronomy/{tool/agent_tool.rb → tools/agent.rb}

@@ -1,16 +1,16 @@
 # frozen_string_literal: true
 
 module Phronomy
-  module Tool
+  module Tools
     # Wraps a Phronomy::Agent::Base subclass as a callable tool so that a parent
     # ReactAgent (or any agent that supports tools) can delegate sub-tasks to a
     # fully-capable agent.
     #
-    # Use AgentTool.from_agent to generate a concrete tool class.  The generated
+    # Use Agent.from_agent to generate a concrete tool class.  The generated
     # class is anonymous; assign it to a constant when you need a stable name.
     #
     # @example Wrap an existing agent
-    #   SummarizerTool = Phronomy::Tool::AgentTool.from_agent(
+    #   SummarizerTool = Phronomy::Tools::Agent.from_agent(
     #     SummarizerAgent,
     #     tool_name:   "summarize",
     #     description: "Summarizes a long text and returns a brief summary"
@@ -21,12 +21,12 @@ module Phronomy
     #     instructions "You are an orchestrator that delegates to specialist agents."
     #     tools SummarizerTool
     #   end
-    class AgentTool < Phronomy::Tool::Base
+    class Agent < Phronomy::Agent::Context::Capability::Base
       description "Wraps an agent as a tool"
       param :input, type: :string, desc: "The input to forward to the wrapped agent"
 
       class << self
-        # Generates a Phronomy::Tool::AgentTool subclass that delegates #execute to
+        # Generates a Phronomy::Tools::Agent subclass that delegates #execute to
         # an instance of +agent_class+.
         #
         # @param agent_class  [Class] a Phronomy::Agent::Base subclass
@@ -34,7 +34,7 @@ module Phronomy
         #   defaults to a snake_case derivation of the agent class name
         # @param description  [String, nil] description exposed to the LLM;
         #   defaults to "Delegates to <AgentClassName>"
-        # @return [Class] an anonymous Phronomy::Tool::AgentTool subclass
+        # @return [Class] an anonymous Phronomy::Tools::Agent subclass
         # @api public
         def from_agent(agent_class, tool_name: nil, description: nil)
           raise ArgumentError, "agent_class must be a Class" unless agent_class.is_a?(Class)

data/lib/phronomy/{tool/mcp_tool.rb → tools/mcp.rb}

@@ -8,8 +8,8 @@ require "shellwords"
 require "uri"
 
 module Phronomy
-  module Tool
-    # A Phronomy::Tool::Base subclass that wraps a tool exposed by an external
+  module Tools
+    # A Phronomy::Agent::Context::Capability::Base subclass that wraps a tool exposed by an external
     # MCP (Model Context Protocol) server.
     #
     # Supports two transport schemes:
@@ -19,15 +19,15 @@ module Phronomy
     #   HTTP/SSE MCP server using +net/http+.
     #
     # @example
-    #   web_search = Phronomy::Tool::McpTool.from_server(
+    #   web_search = Phronomy::Tools::Mcp.from_server(
     #     "stdio://./mcp-server",
     #     tool_name: "search_web"
     #   )
     #   agent = MyAgent.new
     #   agent_class.tools(web_search)
-    class McpTool < Base
+    class Mcp < Phronomy::Agent::Context::Capability::Base
       class << self
-        # Build a McpTool instance by querying a running MCP server for the
+        # Build a Mcp instance by querying a running MCP server for the
         # tool definition identified by +tool_name+.
         #
         # @param server_uri [String] URI of the MCP server.
@@ -35,11 +35,11 @@ module Phronomy
         #   - "stdio://<command>"  — spawn a child process
         #   - "http://<url>" / "https://<url>" — connect to an HTTP/SSE server
         # @param tool_name [String] the tool name as registered in the MCP server
-        # @return [McpTool] a configured subclass instance ready for use with an Agent
+        # @return [Mcp] a configured subclass instance ready for use with an Agent
         # @api public
         def from_server(server_uri, tool_name:)
           # Use a short-lived transport only to query the tool definition,
-          # then close it.  Each McpTool instance creates its own transport
+          # then close it.  Each Mcp instance creates its own transport
           # so that concurrent callers never share IO streams.
           transport = build_transport(server_uri)
           begin
@@ -65,7 +65,7 @@ module Phronomy
         end
 
         def build_tool_class(tool_name, server_uri, tool_def)
-          klass = Class.new(McpTool)
+          klass = Class.new(Mcp)
           klass.tool_name(tool_name)
           klass.instance_variable_set(:@mcp_server_uri, server_uri)
 
@@ -289,7 +289,7 @@ module Phronomy
       # both the 2024-11-05 and 2025-03-26 MCP HTTP transport specifications.
       #
       # @example
-      #   tool = Phronomy::Tool::McpTool.from_server(
+      #   tool = Phronomy::Tools::Mcp.from_server(
       #     "http://localhost:8080/mcp",
       #     tool_name: "weather_lookup"
       #   )