phronomy 0.7.0 → 0.8.0

data/lib/phronomy/invocation_context.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+module Phronomy
+  # Carries all per-invocation context values through the call stack.
+  #
+  # +InvocationContext+ is a plain value object (struct-like, frozen on
+  # creation) that replaces ad-hoc +Thread.current[...]+ propagation.
+  # Pass it explicitly wherever context needs to cross a method boundary
+  # or be handed to a child {Task} / {TaskGroup}.
+  #
+  # @example Build a context for a new agent invocation
+  #   ctx = Phronomy::InvocationContext.new(
+  #     thread_id:         "conv-123",
+  #     cancellation_token: Phronomy::Concurrency::CancellationToken.timeout_after(30),
+  #     max_parallel_tools: 5
+  #   )
+  #   agent.invoke("Hello", invocation_context: ctx)
+  class InvocationContext
+    # @return [String, nil] conversation / workflow thread identifier
+    attr_reader :thread_id
+
+    # @return [String, nil] session identifier (e.g. Rails session id)
+    attr_reader :session_id
+
+    # @return [String, nil] end-user identifier for tracing / audit
+    attr_reader :user_id
+
+    # @return [CancellationToken, nil]
+    attr_reader :cancellation_token
+
+    # @return [Deadline, nil]
+    attr_reader :deadline
+
+    # @return [Object, nil] OpenTelemetry / tracing span
+    attr_reader :tracer_span
+
+    # @return [Integer, nil] max tokens the agent may consume this invocation
+    attr_reader :token_budget
+
+    # @return [Integer] maximum simultaneous tool calls (default: 10)
+    attr_reader :max_parallel_tools
+
+    # @return [Object, nil] approval policy applied before write-scope tools
+    attr_reader :approval_policy
+
+    # @return [Object, nil] redaction policy applied to tool args / results
+    attr_reader :redaction_policy
+
+    # @return [Hash, nil] per-provider concurrency / rate-limit overrides
+    attr_reader :provider_limits
+
+    # @return [String, nil] unique identifier for this task in the trace tree
+    attr_reader :task_id
+
+    # @return [String, nil] task_id of the parent span / task
+    attr_reader :parent_task_id
+
+    # @param thread_id [String, nil]
+    # @param session_id [String, nil]
+    # @param user_id [String, nil]
+    # @param cancellation_token [CancellationToken, nil]
+    # @param deadline [Deadline, nil]
+    # @param tracer_span [Object, nil]
+    # @param token_budget [Integer, nil]
+    # @param max_parallel_tools [Integer]
+    # @param approval_policy [Object, nil]
+    # @param redaction_policy [Object, nil]
+    # @param provider_limits [Hash, nil]
+    # @param task_id [String, nil]
+    # @param parent_task_id [String, nil]
+    # @api private
+    def initialize(
+      thread_id: nil,
+      session_id: nil,
+      user_id: nil,
+      cancellation_token: nil,
+      deadline: nil,
+      tracer_span: nil,
+      token_budget: nil,
+      max_parallel_tools: 10,
+      approval_policy: nil,
+      redaction_policy: nil,
+      provider_limits: nil,
+      task_id: nil,
+      parent_task_id: nil
+    )
+      @thread_id = thread_id
+      @session_id = session_id
+      @user_id = user_id
+      @cancellation_token = cancellation_token
+      @deadline = deadline
+      @tracer_span = tracer_span
+      @token_budget = token_budget
+      @max_parallel_tools = max_parallel_tools
+      @approval_policy = approval_policy
+      @redaction_policy = redaction_policy
+      @provider_limits = provider_limits
+      @task_id = task_id
+      @parent_task_id = parent_task_id
+    end
+
+    # Returns a new +InvocationContext+ with the given attributes merged in.
+    # All other attributes are carried over unchanged.
+    #
+    # @param overrides [Hash] keyword arguments to override
+    # @return [InvocationContext]
+    # @api private
+    def merge(**overrides)
+      InvocationContext.new(
+        thread_id: overrides.fetch(:thread_id, @thread_id),
+        session_id: overrides.fetch(:session_id, @session_id),
+        user_id: overrides.fetch(:user_id, @user_id),
+        cancellation_token: overrides.fetch(:cancellation_token, @cancellation_token),
+        deadline: overrides.fetch(:deadline, @deadline),
+        tracer_span: overrides.fetch(:tracer_span, @tracer_span),
+        token_budget: overrides.fetch(:token_budget, @token_budget),
+        max_parallel_tools: overrides.fetch(:max_parallel_tools, @max_parallel_tools),
+        approval_policy: overrides.fetch(:approval_policy, @approval_policy),
+        redaction_policy: overrides.fetch(:redaction_policy, @redaction_policy),
+        provider_limits: overrides.fetch(:provider_limits, @provider_limits),
+        task_id: overrides.fetch(:task_id, @task_id),
+        parent_task_id: overrides.fetch(:parent_task_id, @parent_task_id)
+      )
+    end
+
+    # Convenience: returns the cancellation token or a new never-cancelled token.
+    # @return [CancellationToken]
+    # @api private
+    def effective_cancellation_token
+      @cancellation_token || Phronomy::Concurrency::CancellationToken.new
+    end
+
+    # Returns the cancellation token to use for an invocation, taking both the
+    # explicit +cancellation_token+ and the +deadline+ into account.
+    #
+    # - When +cancellation_token+ is set, it is returned unchanged.
+    # - When only +deadline+ is set, a new {CancellationToken} is created and
+    #   the deadline is attached to it via {Deadline#attach_to}.
+    # - When neither is set, returns +nil+.
+    #
+    # @return [CancellationToken, nil]
+    # @api private
+    def effective_timeout_token
+      return @cancellation_token if @cancellation_token
+      return nil if @deadline.nil?
+
+      token = Phronomy::Concurrency::CancellationToken.new
+      @deadline.attach_to(token)
+      token
+    end
+  end
+end

data/lib/phronomy/knowledge_source.rb

@@ -1,10 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "knowledge_source/base"
-require_relative "knowledge_source/static_knowledge"
-require_relative "knowledge_source/rag_knowledge"
-require_relative "knowledge_source/entity_knowledge"
-
 module Phronomy
   # KnowledgeSource provides the interface for supplying context region 3 (Knowledge)
   # to the Context::Assembler.

data/lib/phronomy/llm_adapter/base.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module LLMAdapter
+    # Abstract base class for LLM adapters.
+    #
+    # Subclasses must implement {#complete} and {#stream}.
+    # The agent pipeline calls {#complete_async} / {#stream_async} which wrap
+    # those methods in a {BlockingAdapterPool} submission.
+    class Base
+      # Performs a blocking (non-streaming) LLM completion.
+      # Implementors must call +chat.ask(message)+ (or equivalent) and
+      # return the response object.
+      #
+      # @param chat    [Object] the configured chat session object
+      # @param message [String] the user message
+      # @param config  [Hash]  the invocation config (e.g. +:cancellation_token+)
+      # @return [Object] LLM response object
+      # @raise [NotImplementedError]
+      # @api private
+      def complete(chat, message, config: {})
+        raise NotImplementedError, "#{self.class}#complete is not implemented"
+      end
+
+      # Performs a blocking streaming LLM completion.
+      # Implementors must call +chat.ask(message) { |chunk| block.call(chunk) }+
+      # (or equivalent) and return the response object.
+      #
+      # @param chat    [Object] the configured chat session object
+      # @param message [String] the user message
+      # @param config  [Hash]  the invocation config
+      # @yield [chunk] streaming chunk from the LLM
+      # @return [Object] LLM response object
+      # @raise [NotImplementedError]
+      # @api private
+      def stream(chat, message, config: {}, &block)
+        raise NotImplementedError, "#{self.class}#stream is not implemented"
+      end
+
+      # Submits a non-streaming LLM call to {BlockingAdapterPool} and returns
+      # a {BlockingAdapterPool::PendingOperation}.
+      #
+      # @param chat    [Object] configured chat session
+      # @param message [String] user message
+      # @param config  [Hash]  invocation config
+      # @param pool    [BlockingAdapterPool] pool to submit to
+      # @return [BlockingAdapterPool::PendingOperation]
+      # @api private
+      def complete_async(chat, message, config: {}, pool: default_pool)
+        token = config[:cancellation_token]
+        timeout = config[:llm_timeout]
+        pool.submit(timeout: timeout, cancellation_token: token) do
+          complete(chat, message, config: config)
+        end
+      end
+
+      # Submits a streaming LLM call to {BlockingAdapterPool} and returns
+      # a {BlockingAdapterPool::PendingOperation}.
+      #
+      # When +enqueue_to:+ is given, streaming chunks are pushed into that
+      # {AsyncQueue} from the worker thread instead of being passed directly
+      # to the caller's block.  The queue is closed (via +ensure+) after the
+      # LLM call finishes so the consumer's drain loop terminates naturally.
+      # This keeps user-supplied blocks off the blocking-pool worker thread.
+      #
+      # When +enqueue_to:+ is nil and a block is given, the block is invoked
+      # directly from the worker thread (legacy behaviour, preserved for
+      # backward compatibility).
+      #
+      # @param chat       [Object] configured chat session
+      # @param message    [String] user message
+      # @param config     [Hash]   invocation config
+      # @param pool       [BlockingAdapterPool] pool to submit to
+      # @param enqueue_to [AsyncQueue, nil] when set, push chunks here instead of
+      #   calling the block on the worker thread
+      # @yield [chunk] streaming chunk — only used when +enqueue_to:+ is nil
+      # @return [BlockingAdapterPool::PendingOperation]
+      # @api private
+      def stream_async(chat, message, config: {}, pool: default_pool, enqueue_to: nil, &block)
+        token = config[:cancellation_token]
+        timeout = config[:llm_timeout]
+        if enqueue_to
+          pool.submit(timeout: timeout, cancellation_token: token) do
+            stream(chat, message, config: config) do |chunk|
+              enqueue_to.push(chunk)
+            end
+          ensure
+            enqueue_to.close
+          end
+        else
+          pool.submit(timeout: timeout, cancellation_token: token) do
+            stream(chat, message, config: config, &block)
+          end
+        end
+      end
+
+      private
+
+      def default_pool
+        Phronomy::Runtime.instance.blocking_io
+      end
+    end
+  end
+end

data/lib/phronomy/llm_adapter/ruby_llm.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module LLMAdapter
+    # LLM adapter that delegates to the RubyLLM blocking client.
+    #
+    # This is the default adapter used by Phronomy agents.  It wraps
+    # +chat.ask+ (and its streaming variant) so that the blocking HTTP
+    # call runs inside {BlockingAdapterPool} rather than on the EventLoop
+    # thread or the caller's thread directly.
+    #
+    # @example Explicitly configuring this adapter
+    #   Phronomy.configure do |c|
+    #     c.llm_adapter = Phronomy::LLMAdapter::RubyLLM.new
+    #   end
+    class RubyLLM < Base
+      # Delegates to +chat.ask(message)+ or +chat.complete+ when message is nil.
+      #
+      # Passing +nil+ for +message+ is used by the ReAct loop for continuation
+      # turns where the user message has already been added to the chat history
+      # (e.g. after a tool result) and the LLM should continue without a new
+      # user turn.
+      #
+      # @param chat    [Object]      RubyLLM chat session
+      # @param message [String, nil] user message, or nil to continue the chat
+      # @param config  [Hash]        invocation config (not used directly by this impl)
+      # @return [Object] RubyLLM response
+      # @api private
+      def complete(chat, message, config: {})
+        message ? chat.ask(message) : chat.complete
+      end
+
+      # Delegates to +chat.ask(message) { |chunk| block.call(chunk) }+ or
+      # +chat.complete(&block)+ when message is nil.
+      #
+      # @param chat    [Object]      RubyLLM chat session
+      # @param message [String, nil] user message, or nil to continue the chat
+      # @param config  [Hash]        invocation config
+      # @yield [chunk] streaming chunk forwarded from +chat.ask+ / +chat.complete+
+      # @return [Object] RubyLLM response
+      # @api private
+      def stream(chat, message, config: {}, &block)
+        message ? chat.ask(message, &block) : chat.complete(&block)
+      end
+    end
+  end
+end

data/lib/phronomy/llm_adapter.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Phronomy
+  # Namespace for LLM adapter implementations.
+  #
+  # An LLMAdapter decouples Phronomy's agent pipeline from direct
+  # dependency on the RubyLLM blocking client. All LLM calls in
+  # {Agent::Base} are routed through the adapter so that:
+  #
+  # - Blocking HTTP can be submitted to {BlockingAdapterPool} for bounded
+  #   concurrency and per-operation timeouts.
+  # - Alternative LLM clients can be swapped in without changing agent code.
+  #
+  # @example Configuring a custom adapter
+  #   Phronomy.configure do |c|
+  #     c.llm_adapter = MyCustomAdapter.new
+  #   end
+  module LLMAdapter
+  end
+end

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

@@ -3,7 +3,7 @@
 require "cgi"
 
 module Phronomy
-  module Context
+  module LlmContextWindow
     # Assembler collects all four context regions and produces the final
     # {system:, messages:} hash consumed by Agent::Base.
     #
@@ -20,7 +20,7 @@ module Phronomy
     #   messages are passed through unchanged.
     #
     # @example
-    #   assembler = Phronomy::Context::Assembler.new(budget: budget)
+    #   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))
@@ -36,13 +36,15 @@ module Phronomy
       # @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::Context::TokenBudget, nil]
+      # @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
@@ -56,6 +58,7 @@ module Phronomy
       # @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
@@ -71,6 +74,7 @@ module Phronomy
       #   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
@@ -81,6 +85,7 @@ module Phronomy
       # @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
@@ -92,6 +97,7 @@ module Phronomy
       #   :system   [String, nil]  combined system prompt (instruction + knowledge XML tags)
       #   :messages [Array]        conversation messages, trimmed to budget if set
       # @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
       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
@@ -111,11 +117,20 @@ module Phronomy
 
       private
 
+      # 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)

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/loader.rb

@@ -4,10 +4,10 @@ module Phronomy
   # Document loader implementations for ingesting files into a RAG pipeline.
   #
   # Sub-classes are auto-loaded by Zeitwerk:
-  #   Phronomy::Loader::Base
-  #   Phronomy::Loader::PlainTextLoader
-  #   Phronomy::Loader::MarkdownLoader
-  #   Phronomy::Loader::CsvLoader
+  #   Phronomy::Agent::Context::Knowledge::Loader::Base
+  #   Phronomy::Agent::Context::Knowledge::Loader::PlainTextLoader
+  #   Phronomy::Agent::Context::Knowledge::Loader::MarkdownLoader
+  #   Phronomy::Agent::Context::Knowledge::Loader::CsvLoader
   module Loader
   end
 end

data/lib/phronomy/metrics.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Phronomy
+  # Task-centric observability snapshot (Issue #276, extended in #307).
+  #
+  # Collects live metrics from the shared Runtime components
+  # (BlockingAdapterPool, EventLoop, and Runtime task registry) and returns
+  # them as a plain Hash so they can be forwarded to any monitoring backend
+  # (Prometheus, OpenTelemetry, StatsD, etc.).
+  #
+  # All metrics are read at the moment {.snapshot} is called; no
+  # persistent state is held here.
+  #
+  # @example Exporting to a metrics endpoint
+  #   data = Phronomy::Metrics.snapshot
+  #   # => { blocking_pool_active: 2, active_agent_tasks: 1, ... }
+  module Metrics
+    # Returns a Hash of current observability metrics.
+    #
+    # @return [Hash{Symbol => Numeric}]
+    # @api public
+    def self.snapshot
+      pool = Runtime.instance.blocking_io
+      el = EventLoop.instance
+      task_snap = Runtime.instance.task_snapshot
+
+      {
+        blocking_pool_active: pool.active_count,
+        blocking_pool_queue_length: pool.queue_depth,
+        blocking_pool_abandoned_total: pool.abandoned_count,
+        blocking_pool_size: pool.pool_size,
+        event_loop_lag_last_ms: (el.last_lag_seconds * 1000).round(3),
+        event_loop_lag_max_ms: (el.max_lag_seconds * 1000).round(3),
+        event_loop_lag_average_ms: (el.average_lag_seconds * 1000).round(3)
+      }.merge(task_snap)
+    end
+  end
+end

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

@@ -3,7 +3,7 @@
 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
     # exposes to the LLM as a +transfer_to_<name>+ function.
@@ -12,7 +12,7 @@ module Phronomy
     #
     # @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.