phronomy 0.6.0 → 0.7.1

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::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,9 +72,51 @@ module Phronomy
     end
 
     def initialize
-      @queue = Thread::Queue.new  # global event queue (thread-safe; no Mutex needed)
-      @fsms = {}                 # { id => FSMSession }     — EventLoop thread only
-      @waiting = {}                 # { id => completion_queue } — EventLoop thread only
+      @queue = Phronomy::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.
+      @fsm_count_mutex = Mutex.new
+      @fsm_count_cond = ConditionVariable.new
+      @fsm_count = 0
+      # Token cancelled when shutdown is requested; new child sessions receive it.
+      @shutdown_token = Phronomy::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.
@@ -52,20 +130,23 @@ module Phronomy
     # 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
+    # @return [Phronomy::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::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
 
@@ -78,45 +159,146 @@ module Phronomy
     #
     # @param agent_fsm [Phronomy::Agent::FSM]
     # @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 @task&.alive?
+
+      # Reset shutdown state so the loop can be restarted after a stop.
+      @shutdown_token = Phronomy::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
+    # 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] 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 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
+    def stop(timeout: Phronomy.configuration.event_loop_stop_grace_seconds, drain: false, force_kill: false)
+      @shutdown_token.cancel!
+      status = :clean
+
+      if drain
+        # Wait for active sessions to finish, bounded by timeout.
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+        @fsm_count_mutex.synchronize do
+          while @fsm_count > 0
+            remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+            break if remaining <= 0
+            @fsm_count_cond.wait(@fsm_count_mutex, remaining)
+          end
+          status = :drained_with_discards if @fsm_count > 0
+        end
+      end
+
       @running = false
-      @thread&.kill
-      @thread = nil
+      @queue.push(:__stop__)   # unblock queue.pop so the task can see @running = false
+      begin
+        @task&.join(timeout)
+      rescue
+        # 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 @task&.alive?
+        if force_kill
+          Phronomy.configuration.logger&.warn(
+            "[Phronomy] EventLoop task did not stop within #{timeout}s; cancelling. " \
+            "This is a last resort — check for blocking operations in event handlers."
+          )
+          @task.cancel!
+          status = :force_killed
+        else
+          Phronomy.configuration.logger&.warn(
+            "[Phronomy] EventLoop task did not stop within #{timeout}s; abandoning " \
+            "(force_kill: false). Check for blocking operations in event handlers."
+          )
+          status = :timeout
+        end
+      end
+      @task = nil
+      status
     end
 
     private
 
     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 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.
@@ -124,24 +306,87 @@ module Phronomy
           @fsms.delete(event.target_id)
           cq = @waiting.delete(event.target_id)
           cq&.push(event.payload)
+          # Decrement active FSM count and signal drain waiters.
+          @fsm_count_mutex.synchronize do
+            @fsm_count -= 1
+            @fsm_count_cond.signal if @fsm_count <= 0
+          end
 
         when :start
           # session and completion_queue arrive together in the payload so that
           # this thread is the sole writer of @fsms and @waiting.
           # completion may be nil for fire-and-forget child sessions (AgentFSM).
-          @fsms[event.target_id] = event.payload[:session]
+          session = event.payload[:session]
           cq = event.payload[:completion]
+
+          # When shutdown has been requested, reject new sessions with a
+          # CancellationError rather than starting new LLM calls that would
+          # be interrupted by force-kill.
+          if @shutdown_token.cancelled? && cq
+            cq.push(Phronomy::CancellationError.new("EventLoop is shutting down"))
+            next
+          end
+
+          @fsms[event.target_id] = session
           @waiting[event.target_id] = cq if cq
-          event.payload[:session].start
+          @fsm_count_mutex.synchronize { @fsm_count += 1 }
+          session.start
 
         else
-          @fsms[event.target_id]&.handle(event)
+          fsm = @fsms[event.target_id]
+          if fsm
+            fsm.handle(event)
+          else
+            # Warn when an event is dropped due to an unknown target_id so that
+            # mis-typed IDs and handler-deregistration races are visible.
+            warn "[Phronomy::EventLoop] Dropped event #{event.type.inspect} — " \
+                 "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/fsm_session.rb

@@ -49,11 +49,13 @@ module Phronomy
     # @param external_events     [Hash]          { event_name => [{from:, to:, guard:}] }
     # @param phase_machine_class [Class]         state_machines-backed phase tracker class
     # @param recursion_limit     [Integer]
+    # @param action_timeouts     [Hash]          { state_name => seconds }
     # @param resume_event        [Symbol, nil]   external event to fire when resuming
     # @param resume_phase        [Symbol, nil]   wait state name to resume from
+    # @api private
     def initialize(id:, context:, entry_point:, entry_actions:, auto_state_set:,
       declared_states:, wait_state_names:, external_events:, phase_machine_class:,
-      recursion_limit:, resume_event: nil, resume_phase: nil)
+      recursion_limit:, action_timeouts: {}, resume_event: nil, resume_phase: nil)
       @id = id
       @ctx = context
       @entry_point = entry_point
@@ -64,6 +66,7 @@ module Phronomy
       @external_events = external_events
       @phase_machine_class = phase_machine_class
       @recursion_limit = recursion_limit
+      @action_timeouts = action_timeouts
       @resume_event = resume_event
       @resume_phase = resume_phase
       @step = 0
@@ -88,20 +91,60 @@ module Phronomy
         @current_state = @entry_point
         @tracker = build_tracker(@current_state)
         @tracker.context = @ctx
-        (@entry_actions[@current_state] || []).each { |c| c.call(@ctx) }
-        advance_or_halt
+        (@entry_actions[@current_state] || []).each do |c|
+          result = c.call(@ctx)
+          if result.is_a?(Phronomy::Task)
+            # Awaitable action: spawn a task to await without blocking EventLoop.
+            @tracker.async_pending = true
+            session_id = @id
+            current_state_name = @current_state
+            timeout_secs = @action_timeouts[current_state_name]
+            Phronomy::Runtime.instance.spawn(name: "fsm-await-#{session_id}") do
+              if timeout_secs
+                if result.join(timeout_secs).nil?
+                  result.cancel!
+                  raise Phronomy::ActionTimeoutError,
+                    "Action in state #{current_state_name.inspect} timed out after #{timeout_secs}s"
+                end
+              end
+              task_result = result.await
+              if task_result.is_a?(Phronomy::WorkflowContext)
+                event_loop.post(Event.new(type: :action_completed, target_id: session_id, payload: task_result))
+              else
+                event_loop.post(Event.new(type: :state_completed, target_id: session_id, payload: nil))
+              end
+            rescue => e
+              event_loop.post(Event.new(type: :error, target_id: session_id, payload: e))
+            end
+            break # Only one async action at a time per state
+          elsif result.is_a?(Phronomy::WorkflowContext)
+            @ctx = result
+          end
+        end
+        @tracker.context = @ctx
+        advance_or_halt unless @tracker.async_pending
       end
     rescue => e
       finish_with_error(e)
     end
 
     # Processes an event dispatched from EventLoop.
-    # Called for :state_completed and all user-defined external events.
+    # Called for :state_completed, :action_completed, and all user-defined external events.
     #
     # @param event [Phronomy::Event]
+    # @api private
     def handle(event)
       return if @done
 
+      if event.type == :action_completed
+        # An awaitable entry action completed: update context and advance.
+        @ctx = event.payload if event.payload.is_a?(Phronomy::WorkflowContext)
+        @tracker.context = @ctx
+        @tracker.async_pending = false  # Reset flag set by start or fire_and_advance!
+        advance_or_halt
+        return
+      end
+
       fire_and_advance!(event.type)
     rescue => e
       finish_with_error(e)
@@ -118,10 +161,20 @@ module Phronomy
       end
 
       fire_event!(@tracker, event_name, @current_state)
+      @ctx = @tracker.context
       next_phase = @tracker.phase.to_sym
       # When next_phase == @current_state, no transition matched → treat as terminal.
       @current_state = (next_phase == @current_state) ? FINISH : next_phase
       @step += 1
+
+      # If an entry action returned a Task, the after_transition callback set
+      # async_pending = true and spawned a thread. Skip advance_or_halt — the
+      # background thread will post :action_completed or :state_completed.
+      if @tracker.async_pending
+        @tracker.async_pending = false
+        return
+      end
+
       advance_or_halt
     end
 

data/lib/phronomy/generator_verifier.rb

@@ -113,6 +113,7 @@ module Phronomy
     # @param raise_if_untrusted    [Boolean] when +true+, raises
     #   {Phronomy::LowConfidenceError} if the final result does not meet the
     #   confidence threshold (default: false)
+    # @api private
     def initialize(
       draft_agent:,
       review_agent:,
@@ -143,6 +144,7 @@ module Phronomy
     # @return [Result]
     # @raise [Phronomy::LowConfidenceError] when +raise_if_untrusted:+ is +true+
     #   and the result does not meet the confidence threshold
+    # @api private
     def invoke(input, config: {})
       app = compiled_workflow
       state = app.invoke({input: input}, config: config)

data/lib/phronomy/guardrail/base.rb

@@ -17,6 +17,7 @@ module Phronomy
       # Validate the value. Subclasses must implement this method.
       # @param value [Object] the input or output being checked
       # @raise [Phronomy::GuardrailError] if the guardrail rejects the value
+      # @api public
       def check(value)
         raise NotImplementedError, "#{self.class}#check is not implemented"
       end
@@ -24,6 +25,7 @@ module Phronomy
       # Run the check, raising GuardrailError on failure.
       # @param value [Object]
       # @return [Object] the original value (unchanged) when the check passes
+      # @api public
       def run!(value)
         check(value)
         value
@@ -34,6 +36,7 @@ module Phronomy
       # Call inside #check to reject the value.
       # @param reason [String] human-readable rejection reason
       # @raise [Phronomy::GuardrailError]
+      # @api public
       def fail!(reason)
         raise Phronomy::GuardrailError.new(reason, guardrail: self)
       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