phronomy 0.7.0 → 0.8.0

data/lib/phronomy/diagnostics.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Phronomy
+  # Developer-facing diagnostics for blocking operation detection (Issue #279).
+  #
+  # Provides debug dump utilities that can be called from an IRB / Rails console
+  # or in test helpers to inspect the current state of the Runtime.
+  #
+  # @example Enable diagnostics and print a dump
+  #   Phronomy.configure { |c| c.scheduler_debug = true }
+  #   Phronomy::Diagnostics.dump
+  module Diagnostics
+    # Prints a formatted summary of the current Runtime state to +$stderr+
+    # (or the supplied IO).
+    #
+    # Includes:
+    # - BlockingAdapterPool: active workers, queue depth, abandoned count
+    # - EventLoop: last / max / average lag in milliseconds
+    #
+    # @param out [IO] output destination (default: $stderr)
+    # @return [void]
+    # @api public
+    def self.dump(out: $stderr)
+      snap = Phronomy::Metrics.snapshot
+
+      out.puts "[Phronomy::Diagnostics] Runtime state dump"
+      out.puts "  BlockingAdapterPool:"
+      out.puts "    pool_size       : #{snap[:blocking_pool_size]}"
+      out.puts "    active_count    : #{snap[:blocking_pool_active]}"
+      out.puts "    queue_depth     : #{snap[:blocking_pool_queue_length]}"
+      out.puts "    abandoned_total : #{snap[:blocking_pool_abandoned_total]}"
+      out.puts "  EventLoop:"
+      out.puts "    last_lag_ms     : #{snap[:event_loop_lag_last_ms]}"
+      out.puts "    max_lag_ms      : #{snap[:event_loop_lag_max_ms]}"
+      out.puts "    average_lag_ms  : #{snap[:event_loop_lag_average_ms]}"
+    end
+
+    # Returns the diagnostics state as a plain Hash (useful for JSON export).
+    #
+    # @return [Hash]
+    # @api public
+    def self.snapshot
+      Phronomy::Metrics.snapshot
+    end
+
+    # Raises an error if +invoke+ (blocking) is called from inside an EventLoop
+    # action, preventing accidental scheduler stalls.
+    #
+    # Called by Agent::Base#invoke and Workflow#invoke before executing.
+    #
+    # @raise [Phronomy::SchedulerReentrancyError] when called from EventLoop thread
+    # @return [void]
+    # @api private
+    def self.assert_not_in_event_loop!
+      return unless Phronomy::EventLoop.current?
+
+      raise Phronomy::SchedulerReentrancyError,
+        "Blocking invoke called from inside an EventLoop action. " \
+        "Use invoke_async instead."
+    end
+  end
+end

data/lib/phronomy/embeddings.rb

@@ -4,8 +4,8 @@ module Phronomy
   # Embeddings adapters for converting text into vector representations.
   #
   # Sub-classes are auto-loaded by Zeitwerk:
-  #   Phronomy::Embeddings::Base
-  #   Phronomy::Embeddings::RubyLLMEmbeddings
+  #   Phronomy::Agent::Context::Knowledge::Embeddings::Base
+  #   Phronomy::Agent::Context::Knowledge::Embeddings::RubyLLMEmbeddings
   module Embeddings
   end
 end

data/lib/phronomy/eval/runner.rb

@@ -28,29 +28,30 @@ module Phronomy
       # @param concurrency [Integer]  number of parallel threads (default: 1, sequential)
       # @return [Array<EvalResult>]
       # @api public
+      # mutant:disable - concurrency default value mutations (0/2) are genuine equivalent because sequential and concurrent paths produce identical results; if concurrency<=1 boundary mutations (==1 / <1 / <=0 / .eql? / .equal? / false / nil / <=2) are genuine equivalent because the concurrent path with concurrency=1 still produces the same Array<EvalResult> via each_slice(1); spawn name: mutations are genuine equivalent (name is only used for logging)
       def run(dataset, callable, concurrency: 1)
         cases = dataset.to_a
         return cases.map { |eval_case| run_one(eval_case, callable) } if concurrency <= 1
 
-        # Run cases in slices of +concurrency+ threads. Each slice is joined
-        # before the next starts, bounding peak thread count to +concurrency+.
-        # Writing to pre-allocated slots (one per thread) is safe because each
-        # thread writes to a unique index and all threads in a slice are joined
+        # Run cases in slices of +concurrency+ tasks. Each slice is joined
+        # before the next starts, bounding peak task count to +concurrency+.
+        # Writing to pre-allocated slots (one per task) is safe because each
+        # task writes to a unique index and all tasks in a slice are joined
         # before the next slice begins.
-        # Exceptions in worker threads are collected and re-raised after all
-        # threads in the slice are joined, preventing orphaned threads.
+        # Exceptions in worker tasks are collected and re-raised after all
+        # tasks in the slice are joined, preventing orphaned tasks.
         results = Array.new(cases.length)
         cases.each_with_index.each_slice(concurrency) do |batch|
           errors = []
           errors_mu = Mutex.new
-          threads = batch.map do |eval_case, i|
-            Thread.new do
+          tasks = batch.map do |eval_case, i|
+            Phronomy::Runtime.instance.spawn(name: "eval-case-#{i}") do
               results[i] = run_one(eval_case, callable)
             rescue => e
               errors_mu.synchronize { errors << e }
             end
           end
-          threads.each(&:join)
+          tasks.each(&:join)
           raise errors.first if errors.any?
         end
         results
@@ -59,6 +60,7 @@ module Phronomy
       private
 
       # Evaluate a single EvalCase with the given callable and return an EvalResult.
+      # mutant:disable - multiple genuine equivalent mutations: latency_ms=+t0 or =t0 are genuine because :millisecond makes all values Integer so be_a(Integer) passes; (actual,usage)=result is genuine because Ruby multi-assign of a String yields usage=nil identical to extract(); score_safely input: nil/eval_case/absent are genuine because ExactMatch and IncludesScorer ignore the :input kwarg; EvalResult error: nil/absent and usage: nil are genuine because on a successful score run score_error and usage are already nil
       def run_one(eval_case, callable)
         t0 = Process.clock_gettime(Process::CLOCK_MONOTONIC, :millisecond)
         result = callable.call(eval_case.input)
@@ -71,6 +73,7 @@ module Phronomy
       end
 
       # Normalises the callable's return value into [actual_string, usage_or_nil].
+      # mutant:disable - multiple genuine equivalent mutations: is_a?(Hash) vs instance_of?(Hash) (no Hash subclass in practice); to_s vs to_str (String only); result[:output]/[:usage] vs .fetch(:output)/[:usage] (keys always present when is_a?(Hash)); [result.to_s, nil] vs [result.to_s] because actual,usage=[val] → usage=nil via Ruby multi-assign; result.to_s vs result.to_str for String-only values
       def extract(result)
         if result.is_a?(Hash)
           [result[:output].to_s, result[:usage]]
@@ -80,6 +83,7 @@ module Phronomy
       end
 
       # Calls the scorer and returns [score, error]. On failure, returns [0.0, exception].
+      # mutant:disable - [scorer.score(**kwargs), nil] vs [scorer.score(**kwargs)]: because score,error=[val] → error=nil via Ruby multi-assign; both produce the same destructuring in the caller
       def score_safely(scorer, **kwargs)
         [scorer.score(**kwargs), nil]
       rescue => e

data/lib/phronomy/eval/scorer/llm_judge.rb

@@ -45,9 +45,20 @@ module Phronomy
 
         # @return [Float] score in [0.0, 1.0]; 0.0 on error when raise_on_error is false
         # @api public
+        # mutant:disable - multiple genuine equivalent mutations:
+        #   actual.to_str / actual: (shorthand) are genuine (callers pass String);
+        #   expected.to_str / expected: are genuine (String);
+        #   response.content.strip (no to_s) is genuine (content is String);
+        #   lstrip/rstrip/no-strip are genuine (whitespace doesn't affect number scanning);
+        #   scan(/-?\d\.?\d*/) is genuine (for [0,1] range responses, single-digit-before-decimal
+        #     matches are the same after clamp);
+        #   response.content.to_str.strip is genuine (String);
+        #   all warn variations (warn no-arg, warn(nil), warn(e), warn(nil literal),
+        #     nil-replacing-warn, warn-deletion) are genuine because the rescue block
+        #     still returns 0.0 — warn is a side-effect not tested by value assertions
         def score(actual:, expected:, input: nil)
           prompt = format(@prompt_template, input: input.to_s, expected: expected.to_s, actual: actual.to_s)
-          response = RubyLLM.chat(model: @model).ask(prompt)
+          response = Phronomy::Runtime.instance.blocking_io.submit { RubyLLM.chat(model: @model).ask(prompt) }.await
           response.content.to_s.strip.scan(/-?\d+\.?\d*/).first.to_f.clamp(0.0, 1.0)
         rescue => e
           raise if @raise_on_error

data/lib/phronomy/event_loop.rb

@@ -3,12 +3,37 @@
 module Phronomy
   # Singleton event loop that manages all FSMSession instances.
   #
-  # A single background thread reads from a global Thread::Queue and dispatches
-  # events to their target FSMSession. IO work (LLM calls, tool calls) runs in
-  # separate IO threads that post events back to the loop via EventLoop#post.
+  # A single background thread reads from a global {Phronomy::Concurrency::AsyncQueue} and
+  # dispatches events to their target FSMSession.  IO work (LLM calls, tool
+  # calls) must be dispatched via +Runtime.instance.spawn+ or
+  # +BlockingAdapterPool+, then post results back to the loop via
+  # {EventLoop#post}.
   #
   # Activated with: +Phronomy.configure { |c| c.event_loop = true }+
   #
+  # == Threading exception (see ADR-010 Rule 2)
+  #
+  # +EventLoop+ is a **deliberate exception** to Phronomy's cooperative-first
+  # concurrency model.  Its dispatch loop is an infinite +while @running+ loop
+  # that must never block the framework's own event processing.
+  # Running it on a shared scheduler task would consume the scheduler, preventing
+  # other tasks from running.  Therefore {#start} creates a dedicated
+  # {Runtime::ThreadScheduler} — this is correct and intentional per ADR-010.
+  # No other framework component should do the same; see the ADR-010 checklist.
+  #
+  # == Handler constraints
+  #
+  # Handlers dispatched by the EventLoop run **on the EventLoop thread**.
+  # They must not:
+  #
+  # * Perform blocking operations directly (database queries, LLM calls, HTTP
+  #   requests).  Schedule blocking work via +Runtime.instance.spawn+ or
+  #   +BlockingAdapterPool+, then post results back with {#post}.
+  # * Call +Workflow#invoke+ (or any synchronous +invoke+) from within a
+  #   handler.  That method would block waiting for the EventLoop to process
+  #   events, causing a deadlock.  Use the async pattern: post a follow-up
+  #   event instead.
+  #
   # == Fork safety
   #
   # +EventLoop.instance+ is lazily initialized. The background thread is not
@@ -20,14 +45,25 @@ module Phronomy
   # Do NOT call +Workflow#invoke+ (in EventLoop mode) from within a workflow
   # entry action. The entry action runs on the EventLoop thread; a nested
   # +invoke+ would block waiting for the same thread to process events →
-  # deadlock. Use the async IO pattern instead (spawn a Thread, post events
-  # back to the EventLoop).
+  # deadlock. Use the async pattern instead: schedule work via
+  # +Runtime.instance.spawn+ or +BlockingAdapterPool+, then post events back
+  # via +Phronomy::EventLoop.instance.post(...)+.
   class EventLoop
     # Returns the singleton instance, creating and starting it on first call.
     def self.instance
       @instance ||= new.tap(&:start)
     end
 
+    # Returns true when called from within the EventLoop dispatch task.
+    # Uses a task-local key set by the Runtime-spawned dispatch task so that
+    # the check works correctly for both thread-based and future fiber-based
+    # scheduler backends.
+    # @return [Boolean]
+    # @api private
+    def self.current?
+      Phronomy::Task.current&.name == "event-loop"
+    end
+
     # Stops and destroys the singleton. Primarily used in tests.
     # @api private
     def self.reset!
@@ -36,7 +72,7 @@ module Phronomy
     end
 
     def initialize
-      @queue = Thread::Queue.new  # global event queue (thread-safe; no Mutex needed)
+      @queue = Phronomy::Concurrency::AsyncQueue.new  # global event queue (thread-safe; no Mutex needed)
       @fsms = {}                  # { id => FSMSession }     — EventLoop thread only
       @waiting = {}               # { id => completion_queue } — EventLoop thread only
       # Mutex-backed FSM count for drain-mode shutdown.
@@ -44,7 +80,43 @@ module Phronomy
       @fsm_count_cond = ConditionVariable.new
       @fsm_count = 0
       # Token cancelled when shutdown is requested; new child sessions receive it.
-      @shutdown_token = Phronomy::CancellationToken.new
+      @shutdown_token = Phronomy::Concurrency::CancellationToken.new
+      # Fairness metrics (EventLoop thread only, except where noted)
+      @lag_mutex = Mutex.new
+      @last_lag_ns = 0
+      @max_lag_ns = 0
+      @dispatch_count = 0
+      @total_lag_ns = 0
+    end
+
+    # Returns the most recently measured event-loop lag in seconds.
+    # Lag is the wall-clock time between {#post} and the moment the event
+    # is dequeued for dispatch.  Thread-safe.
+    # @return [Float]
+    # @api private
+    def last_lag_seconds
+      @lag_mutex.synchronize { @last_lag_ns } / 1_000_000_000.0
+    end
+
+    # Returns the maximum event-loop lag seen since the loop was started.
+    # Thread-safe.
+    # @return [Float]
+    # @api private
+    def max_lag_seconds
+      @lag_mutex.synchronize { @max_lag_ns } / 1_000_000_000.0
+    end
+
+    # Returns the mean event-loop lag across all dispatched events since the
+    # loop was started.  Returns 0.0 when no events have been dispatched.
+    # Thread-safe.
+    # @return [Float]
+    # @api private
+    def average_lag_seconds
+      @lag_mutex.synchronize do
+        return 0.0 if @dispatch_count.zero?
+
+        @total_lag_ns.to_f / @dispatch_count / 1_000_000_000.0
+      end
     end
 
     # Registers an FSMSession for execution and returns a completion queue.
@@ -57,22 +129,24 @@ module Phronomy
     # (WorkflowContext) once the workflow finishes or halts. If an error occurred,
     # the popped value will be an Exception — callers are responsible for re-raising it.
     #
-    # @param fsm_session [Phronomy::FSMSession]
-    # @return [Thread::Queue] resolves to final/halted context, or an Exception
+    # @param fsm_session [Phronomy::Agent::Lifecycle::FSMSession]
+    # @return [Phronomy::Concurrency::AsyncQueue] resolves to final/halted context, or an Exception
     # @api private
     def register(fsm_session)
-      if Thread.current[:phronomy_event_loop_thread]
+      if Phronomy::EventLoop.current?
         raise Phronomy::Error,
           "Cannot call Workflow#invoke (EventLoop mode) from within an EventLoop " \
-          "entry action. Use the async IO pattern: spawn a Thread, post events " \
-          "back via Phronomy::EventLoop.instance.post(...) instead."
+          "entry action. Schedule work via Runtime.instance.spawn or " \
+          "BlockingAdapterPool, then post events back via " \
+          "Phronomy::EventLoop.instance.post(...) instead."
       end
 
-      completion_queue = Thread::Queue.new
+      completion_queue = Phronomy::Concurrency::AsyncQueue.new
       # Pass both session and completion_queue in the event payload so that the
       # EventLoop thread is the sole writer of @fsms and @waiting.
-      @queue.push(Event.new(type: :start, target_id: fsm_session.id,
-        payload: {session: fsm_session, completion: completion_queue}))
+      @queue.push([Event.new(type: :start, target_id: fsm_session.id,
+        payload: {session: fsm_session, completion: completion_queue}),
+        Process.clock_gettime(Process::CLOCK_MONOTONIC, :nanosecond)])
       completion_queue
     end
 
@@ -87,60 +161,77 @@ module Phronomy
     # @return [nil]
     # @api private
     def enqueue_child(agent_fsm)
-      @queue.push(Event.new(type: :start, target_id: agent_fsm.id,
-        payload: {session: agent_fsm, completion: nil}))
+      @queue.push([Event.new(type: :start, target_id: agent_fsm.id,
+        payload: {session: agent_fsm, completion: nil}),
+        Process.clock_gettime(Process::CLOCK_MONOTONIC, :nanosecond)])
       nil
     end
 
     # Posts an event to the loop. Safe to call from any thread (including IO threads).
+    # The current monotonic clock time is recorded so that the EventLoop can
+    # measure the dispatch lag when it dequeues the event.
     #
+    # @note **Handler constraint**: do not perform blocking operations or call
+    #   +Workflow#invoke+ directly from within the handler that processes a
+    #   posted event.  Handlers run on the EventLoop thread; blocking there
+    #   stalls all session processing.  For blocking work, post a new event
+    #   after the result is ready.
     # @param event [Phronomy::Event]
     # @api private
     def post(event)
-      @queue.push(event)
+      @queue.push([event, Process.clock_gettime(Process::CLOCK_MONOTONIC, :nanosecond)])
     end
 
-    # Starts the background event loop thread.
+    # Starts the EventLoop dispatch task under {Runtime} ownership.
+    #
+    # The dispatch loop runs as a {Phronomy::Task} so that {Runtime#shutdown}
+    # can drain it together with all other in-flight tasks.  The task is named
+    # +"event-loop"+ so that {.current?} can identify it via
+    # +Task.current&.name+.
     # @return [self]
     # @api private
     def start
-      return self if @thread&.alive?
+      return self if @task&.alive?
 
       # Reset shutdown state so the loop can be restarted after a stop.
-      @shutdown_token = Phronomy::CancellationToken.new
+      @shutdown_token = Phronomy::Concurrency::CancellationToken.new
       @fsm_count_mutex.synchronize { @fsm_count = 0 }
       @running = true
-      @thread = Thread.new do
-        Thread.current[:phronomy_event_loop_thread] = true
+      # The dispatch loop must always run in a real background thread.
+      # A cooperative scheduler (FakeScheduler/ImmediateBackend) executes tasks
+      # synchronously on the caller's thread, which would block forever inside
+      # the run_loop infinite loop.  Create a dedicated Runtime with
+      # ThreadScheduler to guarantee async execution regardless of the global
+      # runtime_backend setting.
+      thread_runtime = Phronomy::Runtime.new(scheduler: Phronomy::Runtime::ThreadScheduler.new)
+      @task = thread_runtime.spawn(name: "event-loop") do
         run_loop
       end
-      @thread.abort_on_exception = false
       self
     end
 
-    # Stops the background thread. Used in tests only.
+    # Stops the EventLoop dispatch task.
     #
     # Sends a cooperative shutdown sentinel to the event queue so that the
-    # worker thread can finish any in-flight handler before exiting.  Waits up
-    # to +timeout+ seconds for a clean shutdown; if the thread is still alive
-    # afterwards it is force-killed as a last resort.
+    # dispatch task can finish any in-flight handler before exiting.  Waits up
+    # to +timeout+ seconds for a clean shutdown; if the task is still alive
+    # afterwards it is cancelled (cooperative cancellation via {Task#cancel!}).
     #
     # @param timeout [Numeric] seconds to wait for cooperative shutdown. Defaults
     #   to +Phronomy.configuration.event_loop_stop_grace_seconds+ (5 s).
     # @param drain [Boolean] when +true+, wait for all active FSMSessions to
     #   complete before signalling the loop to stop.  Bounded by +timeout+.
     #   Defaults to +false+.
-    # @param force_kill [Boolean] when +true+, the worker thread is killed with
-    #   +Thread#kill+ if it does not stop within +timeout+. When +false+
-    #   (default), the thread is never killed; the method returns +:timeout+
-    #   instead. +false+ is safer for production because +Thread#kill+ can
-    #   interrupt +ensure+ blocks.
+    # @param force_kill [Boolean] deprecated — retained for backward compatibility.
+    #   When +true+, the dispatch task is cancelled via {Task#cancel!} if it does
+    #   not stop within +timeout+.  +Thread#kill+ is no longer used; cooperative
+    #   cancellation (raising {CancellationError}) replaces it.
     # @return [Symbol] shutdown status:
     #   - +:clean+ — loop exited cooperatively with no active sessions discarded
     #   - +:drained_with_discards+ — drain mode requested but sessions remained;
     #     they were discarded and the loop was stopped
-    #   - +:timeout+ — the worker thread did not stop in time and +force_kill:+ is +false+
-    #   - +:force_killed+ — the worker thread did not stop in time and was killed
+    #   - +:timeout+ — the task did not stop in time and +force_kill:+ is +false+
+    #   - +:force_killed+ — the task was cancelled because it did not stop in time
     # @api private
     def stop(timeout: Phronomy.configuration.event_loop_stop_grace_seconds, drain: false, force_kill: false)
       @shutdown_token.cancel!
@@ -160,31 +251,31 @@ module Phronomy
       end
 
       @running = false
-      @queue.push(:__stop__)   # unblock queue.pop so the worker can see @running = false
+      @queue.push(:__stop__)   # unblock queue.pop so the task can see @running = false
       begin
-        @thread&.join(timeout)
+        @task&.join(timeout)
       rescue
-        # Thread may have terminated with an exception (e.g. simulated crash in
-        # tests). Suppress the re-raise so the cleanup below always runs.
+        # Task may have terminated with an error (e.g. simulated crash in tests).
+        # Suppress the re-raise so the cleanup below always runs.
         nil
       end
-      if @thread&.alive?
+      if @task&.alive?
         if force_kill
           Phronomy.configuration.logger&.warn(
-            "[Phronomy] EventLoop thread did not stop within #{timeout}s; force-killing. " \
+            "[Phronomy] EventLoop task did not stop within #{timeout}s; cancelling. " \
             "This is a last resort — check for blocking operations in event handlers."
           )
-          @thread.kill
+          @task.cancel!
           status = :force_killed
         else
           Phronomy.configuration.logger&.warn(
-            "[Phronomy] EventLoop thread did not stop within #{timeout}s; abandoning " \
+            "[Phronomy] EventLoop task did not stop within #{timeout}s; abandoning " \
             "(force_kill: false). Check for blocking operations in event handlers."
           )
           status = :timeout
         end
       end
-      @thread = nil
+      @task = nil
       status
     end
 
@@ -192,14 +283,22 @@ module Phronomy
 
     def run_loop
       while @running
-        event = @queue.pop
+        item = @queue.pop
         # :__stop__ is used purely as an unblock signal for @queue.pop; the
         # actual stop condition is @running == false (set before the push).
         # Treating it as `next` instead of `break` prevents a stale sentinel
         # (left by a previous stop call that raced with thread start) from
         # immediately terminating a freshly restarted EventLoop.
-        next if event == :__stop__
+        next if item == :__stop__
 
+        # item is [event, posted_at_ns] — unwrap and measure lag
+        event, posted_at_ns = item
+        dequeued_at_ns = Process.clock_gettime(Process::CLOCK_MONOTONIC, :nanosecond)
+        lag_ns = dequeued_at_ns - posted_at_ns
+        update_lag_metrics(lag_ns)
+        check_starvation_lag(lag_ns, event)
+
+        dispatch_start_ns = dequeued_at_ns
         case event.type
         when :finished, :halted, :error
           # All three terminal events share the same cleanup path.
@@ -244,11 +343,50 @@ module Phronomy
                  "no handler for target_id #{event.target_id.inspect}"
           end
         end
+
+        # Check how long this dispatch took; warn if it exceeds the threshold.
+        check_dispatch_time(dispatch_start_ns, event)
       end
     rescue => e
       # Unblock all waiting callers if the loop dies unexpectedly.
       @waiting.values.each { |cq| cq.push(e) }
       raise
     end
+
+    def update_lag_metrics(lag_ns)
+      @lag_mutex.synchronize do
+        @last_lag_ns = lag_ns
+        @max_lag_ns = lag_ns if lag_ns > @max_lag_ns
+        @total_lag_ns += lag_ns
+        @dispatch_count += 1
+      end
+    end
+
+    def check_starvation_lag(lag_ns, event)
+      threshold = Phronomy.configuration.event_loop_starvation_threshold_seconds
+      return unless threshold && lag_ns > (threshold * 1_000_000_000)
+
+      Phronomy.configuration.logger&.warn do
+        "[Phronomy::EventLoop] Starvation detected: event #{event.type.inspect} " \
+        "for target #{event.target_id.inspect} waited " \
+        "#{format("%.3f", lag_ns / 1_000_000_000.0)}s in queue " \
+        "(threshold: #{threshold}s)"
+      end
+    end
+
+    def check_dispatch_time(dispatch_start_ns, event)
+      threshold = Phronomy.configuration.event_loop_dispatch_threshold_seconds
+      return unless threshold
+
+      elapsed_ns = Process.clock_gettime(Process::CLOCK_MONOTONIC, :nanosecond) - dispatch_start_ns
+      return unless elapsed_ns > (threshold * 1_000_000_000)
+
+      Phronomy.configuration.logger&.warn do
+        "[Phronomy::EventLoop] Long dispatch: event #{event.type.inspect} " \
+        "for target #{event.target_id.inspect} took " \
+        "#{format("%.3f", elapsed_ns / 1_000_000_000.0)}s on the EventLoop thread " \
+        "(threshold: #{threshold}s). Consider moving blocking work to BlockingAdapterPool."
+      end
+    end
   end
 end

data/lib/phronomy/guardrail/prompt_injection_guardrail.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Guardrail
+    # Detects potential prompt injection attempts in the agent input.
+    #
+    # Prompt injection is an attack where an adversary embeds LLM instructions
+    # inside data sources (e.g. RAG chunks, tool results, user input) to override
+    # the agent's intended behaviour.
+    #
+    # This guardrail scans the input string for common injection patterns and
+    # calls {#fail!} when a match is found.  It is intended to be registered as
+    # an input guardrail on agents that consume untrusted external content.
+    #
+    # @example
+    #   class MyAgent < Phronomy::Agent::Base
+    #     model "gpt-4o"
+    #     input_guardrails Phronomy::Guardrail::PromptInjectionGuardrail.new
+    #   end
+    #
+    # @example Custom patterns
+    #   guard = Phronomy::Guardrail::PromptInjectionGuardrail.new(
+    #     extra_patterns: [/exfiltrate/i]
+    #   )
+    class PromptInjectionGuardrail < InputGuardrail
+      # Common prompt injection / jailbreak patterns.
+      DEFAULT_PATTERNS = [
+        /ignore\s+(previous|prior|all)\s+instructions?/i,
+        /disregard\s+(previous|prior|all)\s+instructions?/i,
+        /forget\s+(previous|prior|all)\s+instructions?/i,
+        /override\s+(previous|prior|all)\s+instructions?/i,
+        /new\s+instructions?:\s/i,
+        /\byour\s+new\s+(role|instructions?|task)\b/i,
+        /you\s+are\s+now\s+(a|an)\b/i,
+        /\bact\s+as\s+(a|an)\b/i,
+        /\bpretend\s+(you\s+are|to\s+be)\b/i,
+        /\bdo\s+not\s+follow\s+(your|the)\s+instructions?\b/i
+      ].freeze
+
+      # @param extra_patterns [Array<Regexp>] additional patterns to scan for
+      # @api private
+      def initialize(extra_patterns: [])
+        super()
+        @patterns = DEFAULT_PATTERNS + extra_patterns
+      end
+
+      # Scans the input string for injection patterns.
+      # @param input [String, Hash]
+      # @api private
+      def check(input)
+        text = input.is_a?(Hash) ? input.values.join(" ") : input.to_s
+        @patterns.each do |pattern|
+          fail!("Potential prompt injection detected") if text.match?(pattern)
+        end
+      end
+    end
+  end
+end