phronomy 0.8.0 → 0.9.0

data/lib/phronomy/agent/context/capability/scope_policy.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    module Context
+      module Capability
+        # Evaluates whether a tool with a given scope may execute.
+        #
+        # A ScopePolicy is a callable that receives +(tool_class, scope, agent)+ and
+        # returns one of:
+        #   +:allow+   — proceed immediately without an approval gate.
+        #   +:reject+  — block execution; the tool returns a denial message.
+        #   +:approve+ — delegate to the agent's approval handler (if registered);
+        #                when no handler is registered the call is rejected.
+        #
+        # The {Default} instance is used automatically when no custom policy is
+        # configured on an agent.
+        #
+        # @example Custom policy that allows everything
+        #   agent.scope_policy = ->(_tool_class, _scope, _agent) { :allow }
+        #
+        # @example Strict policy that rejects all write scopes
+        #   agent.scope_policy = ->(_tc, scope, _agent) {
+        #     scope == :write ? :reject : :allow
+        #   }
+        class ScopePolicy
+          # Scopes that must go through an approval gate before execution.
+          APPROVAL_REQUIRED_SCOPES = %i[write admin external_network filesystem process external_process].freeze
+
+          # Scopes that are always permitted without approval.
+          ALWAYS_ALLOWED_SCOPES = %i[read_only].freeze
+
+          # Returns +:allow+ for always-allowed scopes, +:approve+ for high-risk
+          # scopes, and +:allow+ for anything else (including +nil+).
+          #
+          # @param _tool_class [Class]
+          # @param scope [Symbol, nil]
+          # @param _agent [Object]
+          # @return [:allow, :approve, :reject]
+          # @api private
+          def call(_tool_class, scope, _agent)
+            return :allow if scope.nil? || ALWAYS_ALLOWED_SCOPES.include?(scope)
+            return :approve if APPROVAL_REQUIRED_SCOPES.include?(scope)
+
+            :allow
+          end
+
+          # Shared singleton used when no custom policy is configured.
+          DEFAULT = new.freeze
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/agent/context/knowledge/base.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    module Context
+      module Knowledge
+        # Abstract base class for all KnowledgeSource implementations.
+        #
+        # Subclasses must implement #fetch(query:) and return an Array of chunk Hashes.
+        # Each chunk Hash must contain:
+        #   :content [String]  the text to inject into the context
+        #   :type    [Symbol]  semantic tag (e.g. :static, :rag, :entity)
+        class Base
+          # Retrieve knowledge chunks relevant to the given query.
+          #
+          # @param query              [String, nil]                    the current user input used to select relevant chunks
+          # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil] optional token; raises CancellationError when cancelled
+          # @return [Array<Hash>] array of { content: String, type: Symbol }
+          # @api public
+          def fetch(query: nil, cancellation_token: nil)
+            cancellation_token&.raise_if_cancelled!
+            raise NotImplementedError, "#{self.class}#fetch is not implemented"
+          end
+
+          # Submits a {#fetch} call to {BlockingAdapterPool} and returns a
+          # {BlockingAdapterPool::PendingOperation}.
+          # Callers can fan out multiple fetches in parallel and await them all.
+          #
+          # @param query              [String, nil]
+          # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil]
+          # @param timeout            [Numeric, nil] seconds before the operation is abandoned
+          # @return [BlockingAdapterPool::PendingOperation]
+          # @api public
+          def fetch_async(query: nil, cancellation_token: nil, timeout: nil)
+            Phronomy::Runtime.instance.blocking_io.submit(
+              timeout: timeout,
+              cancellation_token: cancellation_token
+            ) do
+              fetch(query: query, cancellation_token: cancellation_token)
+            end
+          end
+
+          # Returns true when this source's content is considered static (i.e. does
+          # not change between agent invocations). Static sources are eligible for
+          # fingerprint-based caching in ContextVersionCache.
+          #
+          # Override in subclasses that return fixed content.
+          #
+          # @return [Boolean]
+          # @api public
+          def static?
+            false
+          end
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/agent/context/knowledge/entity_knowledge.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    module Context
+      module Knowledge
+        # A KnowledgeSource that extracts named-entity facts from conversation history.
+        #
+        # This is the knowledge-injection counterpart of the old EntityMemory.
+        # It scans saved user messages with a regex heuristic (no LLM call) and
+        # returns the discovered facts as a single knowledge chunk tagged :entity.
+        #
+        # EntityKnowledge is stateful: it accumulates extracted facts via #update(messages:)
+        # which should be called each time new messages are saved.
+        #
+        # Supported extraction patterns (case-insensitive):
+        #   "my name is Alice"          → { name: "Alice" }
+        #   "I am Alice"                → { identity: "Alice" }
+        #   "I'm a software engineer"   → { occupation: "software engineer" }
+        #   "I work at / for Acme"      → { workplace: "Acme" }
+        #   "I live in Tokyo"           → { location: "Tokyo" }
+        #   "I'm from Tokyo"            → { location: "Tokyo" }
+        #   "I like / love Ruby"        → { preference: "Ruby" }
+        #
+        # @example
+        #   ks = Phronomy::Agent::Context::Knowledge::EntityKnowledge.new
+        #   ks.update(messages: chat_messages)
+        #   agent = MyAgent.new
+        #   agent.add_knowledge_source(ks)
+        #   agent.invoke("What is my name?")
+        class EntityKnowledge < Base
+          PATTERNS = [
+            [:name, /\bmy name is\s+([A-Za-z][A-Za-z0-9 \-']*)/i],
+            [:identity, /\bI\s+am\s+([A-Z][A-Za-z0-9 \-']+)/],
+            [:occupation, /\bI(?:'m| am) a(?:n)?\s+([A-Za-z][A-Za-z0-9 \-']*)/i],
+            [:workplace, /\bI (?:work|worked) (?:at|for|in)\s+([A-Za-z0-9][A-Za-z0-9 \-'.&,]*)/i],
+            [:location, /\bI live in\s+([A-Za-z][A-Za-z0-9 \-']*)/i],
+            [:location, /\bI(?:'m| am) from\s+([A-Za-z][A-Za-z0-9 \-']*)/i],
+            [:preference, /\bI (?:like|love|enjoy)\s+([A-Za-z][A-Za-z0-9 \-']*)/i]
+          ].freeze
+
+          def initialize
+            @entities = {}
+          end
+
+          # Scan messages and accumulate entity facts.
+          # Call this after saving a new set of messages (e.g. from a ConversationManager save hook).
+          #
+          # @param messages [Array] message objects responding to #role and #content
+          # @api public
+          def update(messages:)
+            messages.each do |msg|
+              next unless msg.role.to_sym == :user
+
+              extract(msg.content.to_s).each { |key, value| @entities[key] = value }
+            end
+          end
+
+          # Returns a single chunk containing all known entity facts in XML context format.
+          # Returns an empty array when no entities have been discovered.
+          #
+          # @param query              [String, nil]                    unused — entity knowledge is always fully injected
+          # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil] optional; raises CancellationError when cancelled
+          # @return [Array<Hash>]
+          # @api public
+          def fetch(query: nil, cancellation_token: nil)
+            cancellation_token&.raise_if_cancelled!
+            return [] if @entities.empty?
+
+            lines = @entities.map { |key, value| "- #{key}: #{value}" }.join("\n")
+            content = <<~CONTENT.chomp
+              Known facts about the user:
+              #{lines}
+            CONTENT
+            [{content: content, type: :entity}]
+          end
+
+          # Returns the current entity store (primarily for testing).
+          #
+          # @return [Hash]
+          # @api public
+          def entities
+            @entities.dup
+          end
+
+          private
+
+          def extract(text)
+            found = {}
+            PATTERNS.each do |key, pattern|
+              if (match = text.match(pattern))
+                value = match[1].strip.sub(/[.!?]\s+.*$/, "").gsub(/[.,;!?]+$/, "")
+                found[key] = value unless value.empty?
+              end
+            end
+            found
+          end
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/agent/context/knowledge/static_knowledge.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    module Context
+      module Knowledge
+        # A KnowledgeSource backed by fixed text provided at construction time.
+        #
+        # Useful for injecting static documents, policy files, or configuration
+        # knowledge that does not change per request.
+        #
+        # @example
+        #   ks = Phronomy::Agent::Context::Knowledge::StaticKnowledge.new(
+        #     "Our refund policy: ...",
+        #     type: :policy
+        #   )
+        #   agent = MyAgent.new
+        #   agent.add_knowledge_source(ks)
+        #   agent.invoke("What is the refund policy?")
+        class StaticKnowledge < Base
+          # @param text   [String] the static knowledge text to inject
+          # @param type   [Symbol] semantic tag for the chunk (default :static)
+          # @param source [String, nil] label identifying where this knowledge came from
+          #   (e.g. a filename). Included in the context XML tag and exposed to the LLM
+          #   so that agents can produce grounded citations.
+          # @api public
+          def initialize(text, type: :static, source: nil)
+            @text = text.to_s
+            @type = type
+            @source = source
+          end
+
+          # Returns the fixed text as a single chunk, regardless of query.
+          #
+          # @param query              [String, nil]                    ignored for static knowledge
+          # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil] optional; raises CancellationError when cancelled
+          # @return [Array<Hash>]
+          # @api public
+          def fetch(query: nil, cancellation_token: nil)
+            cancellation_token&.raise_if_cancelled!
+            return [] if @text.empty?
+
+            chunk = {content: @text, type: @type}
+            chunk[:source] = @source if @source
+            [chunk]
+          end
+
+          # Static knowledge content never changes between invocations.
+          # @return [true]
+          # @api public
+          def static?
+            true
+          end
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/agent/invocation_pipeline.rb

@@ -43,8 +43,17 @@ module Phronomy
 
           # Assemble context (system prompt + history). Override #build_context to
           # inject custom context editing logic at the Agent subclass level.
-          context = build_context(inp, messages: msgs, thread_id: tid, config: cfg)
+          context = build_context(
+            inp,
+            messages: msgs,
+            thread_id: tid,
+            config: cfg,
+            budget: build_token_budget,
+            instruction: build_instructions(inp),
+            tools: self.class.tools + _handoff_tools
+          )
           apply_instructions(chat, context[:system]) if context[:system]
+          (context[:tool_classes] || []).each { |tc| chat.with_tool(prepare_tool_class(tc)) }
           context[:messages].each { |msg| chat.messages << msg }
 
           # Run before_completion hooks (global → class → instance) before the LLM call.

data/lib/phronomy/agent/react_agent.rb

@@ -117,20 +117,18 @@ module Phronomy
       def step(messages, initial_input, user_asked: false, thread_id: nil, config: {})
         chat = build_chat
 
-        if user_asked
-          # Subsequent loop iteration — messages already contains the full conversation
-          # (including the user's original input from the first step); apply system
-          # instructions and replay the accumulated history, then let the LLM continue.
-          system_text = build_cached_system_text(initial_input)
-          apply_instructions(chat, system_text) if system_text
-          messages.each { |m| chat.add_message(m) }
-        else
-          # First iteration — assemble context (system + history) via build_context so
-          # that trimming, compaction, and knowledge sources are applied consistently.
-          context = build_context(initial_input, messages: messages, thread_id: thread_id, config: config)
-          apply_instructions(chat, context[:system]) if context[:system]
-          context[:messages].each { |m| chat.messages << m }
-        end
+        context = build_context(
+          initial_input,
+          messages: messages,
+          thread_id: thread_id,
+          config: config,
+          budget: build_token_budget,
+          instruction: build_instructions(initial_input),
+          tools: self.class.tools + _handoff_tools
+        )
+        apply_instructions(chat, context[:system]) if context[:system]
+        (context[:tool_classes] || []).each { |tc| chat.with_tool(prepare_tool_class(tc)) }
+        context[:messages].each { |m| chat.add_message(m) }
 
         # Run before_completion hooks before each LLM call in the ReAct loop.
         run_before_completion_hooks!(chat, config)
@@ -155,15 +153,18 @@ module Phronomy
       def stream_step(messages, initial_input, user_asked: false, thread_id: nil, config: {}, &block)
         chat = build_chat
 
-        if user_asked
-          system_text = build_cached_system_text(initial_input)
-          apply_instructions(chat, system_text) if system_text
-          messages.each { |m| chat.add_message(m) }
-        else
-          context = build_context(initial_input, messages: messages, thread_id: thread_id, config: config)
-          apply_instructions(chat, context[:system]) if context[:system]
-          context[:messages].each { |m| chat.messages << m }
-        end
+        context = build_context(
+          initial_input,
+          messages: messages,
+          thread_id: thread_id,
+          config: config,
+          budget: build_token_budget,
+          instruction: build_instructions(initial_input),
+          tools: self.class.tools + _handoff_tools
+        )
+        apply_instructions(chat, context[:system]) if context[:system]
+        (context[:tool_classes] || []).each { |tc| chat.with_tool(prepare_tool_class(tc)) }
+        context[:messages].each { |m| chat.add_message(m) }
 
         current_tool_call = nil
         chat.on_tool_call do |tc|

data/lib/phronomy/agent/shared_state.rb

@@ -239,7 +239,7 @@ module Phronomy
       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::Tool::Base) do
+        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."
@@ -247,7 +247,7 @@ module Phronomy
           define_method(:execute) { store.read_all.to_json }
         end
 
-        write_tool = Class.new(Phronomy::Tool::Base) do
+        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."

data/lib/phronomy/agent/tool_executor.rb

@@ -51,7 +51,7 @@ module Phronomy
       # Dispatches a single tool call asynchronously according to its
       # +execution_mode+ and returns an awaitable.
       #
-      # @param tool               [Phronomy::Tool::Base] the tool instance to invoke
+      # @param tool               [Phronomy::Agent::Context::Capability::Base] the tool instance to invoke
       # @param args               [Hash]                 argument hash to pass to {Tool::Base#call}
       # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil]
       # @param runtime            [Phronomy::Runtime]    runtime to use for spawning

data/lib/phronomy/concurrency/gate_registry.rb

@@ -14,7 +14,6 @@ module Phronomy
         tool: :max_concurrent_tool_tasks,
         workflow: :max_concurrent_workflow_tasks,
         llm: :max_concurrent_llm_calls,
-        rag: :max_concurrent_rag_fetches,
         vector: :max_concurrent_vector_searches
       }.freeze
       private_constant :GATE_CONFIG_MAP

data/lib/phronomy/configuration.rb

@@ -140,11 +140,6 @@ module Phronomy
     # @return [Integer, nil]
     attr_accessor :stream_queue_max_size
 
-    # Maximum number of concurrent RAG knowledge-source fetches in-flight.
-    # nil = unlimited (default).
-    # @return [Integer, nil]
-    attr_accessor :max_concurrent_rag_fetches
-
     # Maximum number of concurrent vector-store searches in-flight.
     # nil = unlimited (default).
     # @return [Integer, nil]
@@ -204,7 +199,6 @@ module Phronomy
       @max_concurrent_workflow_tasks = nil
       @max_concurrent_llm_calls = nil
       @stream_queue_max_size = nil
-      @max_concurrent_rag_fetches = nil
       @max_concurrent_vector_searches = nil
       @starvation_threshold_ms = 50
       @runtime_backend = :thread

data/lib/phronomy/llm_context_window/assembler.rb

@@ -5,19 +5,21 @@ require "cgi"
 module Phronomy
   module LlmContextWindow
     # Assembler collects all four context regions and produces the final
-    # {system:, messages:} hash consumed by Agent::Base.
+    # {system:, messages:, tool_classes:} hash consumed by Agent::Base.
     #
     # Regions:
     #   1. Instruction  — system prompt text set via #add_instruction
-    #   2. Capability   — tool definitions (handled by RubyLLM, not here)
+    #   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. 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.
+    #   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)
@@ -48,10 +50,23 @@ module Phronomy
       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.
       #
@@ -91,68 +106,86 @@ module Phronomy
         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
+      #   :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
-      # mutant:disable - multiple genuine equivalent mutations: map{}.join("\n\n") → map{} is genuine because Ruby Array#join recursively joins nested arrays with the same separator (so [outer_array].join("\n\n") == original String); `unless knowledge_text.empty?` vs ternary is genuine (same conditional logic); `{ system: unless system_text.empty? }` vs ternary is genuine; `messages:` shorthand vs `messages: messages` is genuine
+      # 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")
 
-        messages = if @budget
-          trim_messages_to_budget(@messages, system_text)
-        else
-          @messages
+        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
+          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
-
-      # mutant:disable - multiple genuine equivalent mutations on the early-return guard:
-      # `remaining <= 0 && false/nil`, `if false`, `if nil`, `if remaining && messages.empty?`,
-      # `if remaining < 0 && messages.empty?`, `if remaining <= -1 && messages.empty?`,
-      # `if remaining <= 1 && messages.empty?`, `if remaining == 0 && messages.empty?`,
-      # `if remaining.eql?(0) && messages.empty?`, `if remaining.equal?(0) && messages.empty?`,
-      # `if 0 && messages.empty?`, `if nil && messages.empty?` —
-      # all are genuine equivalents because when messages.empty? the loop produces [] anyway,
-      # and remaining is always >= 0 (clamp(0..)) so `remaining < 0` / `<= -1` are never true.
-      def trim_messages_to_budget(messages, system_text)
-        used = TokenEstimator.estimate(system_text)
-        remaining = @budget.available(used: used)
-        return messages if remaining <= 0 && messages.empty?
-
-        accumulated = 0
-        result = []
-        messages.reverse_each do |msg|
-          tokens = TokenEstimator.estimate(msg.content.to_s)
-          break if accumulated + tokens > remaining
-
-          accumulated += tokens
-          result.push(msg)
-        end
-
-        if result.empty? && messages.any?
-          warn "[Phronomy::Assembler] All #{messages.length} conversation message(s) dropped: " \
-               "token budget exhausted by system context (budget=#{@budget.context_window}, used_by_system=#{used})"
-        end
-
-        result.reverse
-      end
     end
   end
 end

data/lib/phronomy/multi_agent/handoff.rb

@@ -5,7 +5,7 @@ require "securerandom"
 module Phronomy
   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.
@@ -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/multi_agent/orchestrator.rb

@@ -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"

data/lib/phronomy/multi_agent/team_coordinator.rb

@@ -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),