phronomy 0.7.1 → 0.8.0

data/lib/phronomy/concurrency/cancellation_token.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Concurrency
+    # Provides cooperative cancellation for agent invocations.
+    #
+    # Pass a token to an agent via +config: { cancellation_token: token }+.
+    # The agent checks the token before each LLM call and raises
+    # {Phronomy::CancellationError} when the token is cancelled or the
+    # optional deadline has passed.
+    #
+    # A token may be shared across multiple agent invocations and across threads;
+    # all access to internal state is protected by a Mutex.
+    #
+    # @example Explicit cancel from another thread
+    #   token = Phronomy::Concurrency::CancellationToken.new
+    #   Thread.new { sleep 5; token.cancel! }
+    #   result = agent.invoke("...", config: { cancellation_token: token })
+    #
+    # @example Hard deadline via monotonic clock (recommended)
+    #   token = Phronomy::Concurrency::CancellationToken.timeout_after(30)
+    #   result = agent.invoke("...", config: { cancellation_token: token })
+    #
+    # @example Hard deadline via wall-clock (legacy)
+    #   token = Phronomy::Concurrency::CancellationToken.new(deadline: Time.now + 30)
+    #   result = agent.invoke("...", config: { cancellation_token: token })
+    #
+    # @example Propagate to parallel workers
+    #   token = Phronomy::Concurrency::CancellationToken.new
+    #   orchestrator.dispatch_parallel(task1, task2, cancellation_token: token)
+    class CancellationToken
+      # Returns a new token that will expire after +seconds+ seconds, measured
+      # with the monotonic clock (+Process::CLOCK_MONOTONIC+). Unlike constructing
+      # a token with +deadline: Time.now + seconds+, this factory is immune to NTP
+      # adjustments and DST transitions.
+      #
+      # @param seconds [Numeric] duration in seconds until the token expires.
+      # @return [CancellationToken]
+      # @api public
+      def self.timeout_after(seconds)
+        monotonic_deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + seconds
+        new(monotonic_deadline: monotonic_deadline)
+      end
+
+      # @param deadline [Time, nil] optional wall-clock deadline; the token reports
+      #   +cancelled?+ as +true+ once +Time.now >= deadline+.  Prefer
+      #   {.timeout_after} for duration-based cancellation.
+      # @param monotonic_deadline [Float, nil] internal monotonic timestamp set by
+      #   {.timeout_after}; prefer that factory method over passing this directly.
+      # @api public
+      # mutant:disable - removing @cancelled = false is equivalent because nil is falsey
+      def initialize(deadline: nil, monotonic_deadline: nil)
+        @cancelled = false
+        @deadline = deadline
+        @monotonic_deadline = monotonic_deadline
+        @mutex = Mutex.new
+        @cancel_callbacks = []
+      end
+
+      # @return [Time, nil] the wall-clock deadline passed to {#initialize}, or +nil+.
+      attr_reader :deadline
+
+      # Returns the remaining seconds until the monotonic deadline fires, or +nil+
+      # when no monotonic deadline is set.  Returns 0.0 if already past.
+      # @return [Float, nil]
+      # @api public
+      def remaining_monotonic_seconds
+        return nil if @monotonic_deadline.nil?
+        remaining = @monotonic_deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        [remaining, 0.0].max
+      end
+
+      # Registers a one-shot callback invoked when this token is explicitly
+      # cancelled via {#cancel!}.  If the token is already cancelled, the block
+      # is called immediately (still within the caller's thread).
+      #
+      # Callbacks are NOT fired for deadline-based cancellation (i.e. when
+      # {#cancelled?} returns +true+ due to +@monotonic_deadline+ expiry).  Use
+      # {Runtime#timer_queue} to schedule deadline callbacks.
+      #
+      # @yield called with no arguments when (or if) the token is cancelled
+      # @return [self]
+      # @api public
+      # mutant:disable - mutex removal mutation is GVL-safe equivalent under MRI
+      def on_cancel(&block)
+        already_cancelled = @mutex.synchronize do
+          if @cancelled
+            true
+          else
+            @cancel_callbacks << block
+            false
+          end
+        end
+        block.call if already_cancelled
+        self
+      end
+
+      # Mark the token as cancelled and fire any registered {#on_cancel} callbacks.
+      # Thread-safe; idempotent — calling multiple times has no additional effect.
+      # @return [self]
+      # @api public
+      # mutant:disable - mutex removal and dup-vs-ref mutations are GVL-safe equivalents
+      def cancel!
+        callbacks = @mutex.synchronize do
+          return self if @cancelled
+          @cancelled = true
+          @cancel_callbacks.dup
+        end
+        callbacks.each(&:call)
+        self
+      end
+
+      # Returns +true+ when the token has been explicitly cancelled via {#cancel!},
+      # when the wall-clock deadline has passed, or when the monotonic deadline
+      # (set by {.timeout_after}) has elapsed. Thread-safe.
+      # @return [Boolean]
+      # @api public
+      # mutant:disable - mutex removal on @cancelled read is GVL-safe equivalent under MRI
+      def cancelled?
+        return true if @mutex.synchronize { @cancelled }
+        return true if !@deadline.nil? && Time.now >= @deadline
+        !@monotonic_deadline.nil? &&
+          Process.clock_gettime(Process::CLOCK_MONOTONIC) >= @monotonic_deadline
+      end
+
+      # Raises {Phronomy::CancellationError} if the token is cancelled.
+      # A convenience method for cooperative cancellation checks inside tools,
+      # RAG loaders, and hooks, replacing the +if cancelled? then raise+ pattern.
+      #
+      # @param message [String] optional error message
+      # @return [nil] when the token is not cancelled
+      # @raise [Phronomy::CancellationError] when the token is cancelled
+      # @api public
+      # mutant:disable - raise(CancellationError) resolves to raise(Phronomy::CancellationError) in this namespace
+      def raise_if_cancelled!(message = "invocation cancelled")
+        raise Phronomy::CancellationError, message if cancelled?
+      end
+    end
+  end
+end

data/lib/phronomy/concurrency/concurrency_gate.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Concurrency
+    # A counting semaphore that enforces a concurrency cap across a named
+    # resource category (e.g. agent tasks, tool tasks, LLM calls).
+    #
+    # When +max_concurrent+ is +nil+ the gate is a no-op and all callers
+    # pass through immediately without acquiring a slot.
+    #
+    # Backpressure behaviour when the gate is full is controlled by the
+    # +on_full:+ keyword:
+    #   +:reject+  — raise {Phronomy::BackpressureError} immediately
+    #   +:wait+    — block the calling fiber/thread until a slot is free
+    #   +:timeout+ — like +:wait+ but raises {Phronomy::BackpressureError}
+    #               after +timeout:+ seconds if no slot becomes available
+    #
+    # @example
+    #   gate = Phronomy::Concurrency::ConcurrencyGate.new(max_concurrent: 5, name: :agent)
+    #   gate.acquire(on_full: :reject) do
+    #     run_agent_task
+    #   end
+    class ConcurrencyGate
+      # @param max_concurrent [Integer, nil] concurrency cap; nil = unlimited
+      # @param name [Symbol, String, nil] human-readable label used in error messages
+      # @api private
+      def initialize(max_concurrent:, name: nil)
+        @max = max_concurrent
+        @name = name
+        @mutex = Mutex.new
+        @cond = ConditionVariable.new
+        @count = 0
+      end
+
+      # Returns the configured cap (or nil when unlimited).
+      attr_reader :max
+
+      # Returns the name label.
+      attr_reader :name
+
+      # Returns the number of slots currently in use.
+      def current_count
+        @mutex.synchronize { @count }
+      end
+
+      # Acquires a slot, executes +block+, then releases the slot.
+      # When the gate is unlimited (max is nil) the block runs directly.
+      #
+      # @param on_full [:reject, :wait, :timeout] backpressure strategy
+      # @param timeout [Numeric, nil] seconds before +:timeout+ gives up
+      # @yield
+      # @return block return value
+      # @raise [Phronomy::BackpressureError] when +:reject+ or +:timeout+ fires
+      # @api private
+      def acquire(on_full: :wait, timeout: nil, &block)
+        return block.call if @max.nil?
+
+        _acquire_slot(on_full: on_full, timeout: timeout)
+        begin
+          block.call
+        ensure
+          _release_slot
+        end
+      end
+
+      private
+
+      def _acquire_slot(on_full:, timeout:)
+        scheduler = Phronomy::Runtime::Scheduler.current
+        if scheduler
+          _acquire_slot_coop(scheduler, on_full: on_full, timeout: timeout)
+        else
+          _acquire_slot_threaded(on_full: on_full, timeout: timeout)
+        end
+      end
+
+      def _acquire_slot_coop(scheduler, on_full:, timeout:)
+        # In cooperative mode all tasks run on the same thread, so no mutex needed.
+        deadline = timeout ? (scheduler.virtual_time + timeout) : nil
+        @coop_signal ||= scheduler.new_signal
+
+        loop do
+          if @count < @max
+            @count += 1
+            return
+          end
+
+          case on_full
+          when :reject
+            raise Phronomy::BackpressureError,
+              "ConcurrencyGate[#{@name}] at capacity (#{@max}); " \
+              "increase max_concurrent_#{@name}_tasks or retry later"
+          when :timeout
+            if deadline && scheduler.virtual_time >= deadline
+              raise Phronomy::BackpressureError,
+                "ConcurrencyGate[#{@name}] timed out waiting for a free slot (cap: #{@max})"
+            end
+            scheduler.wait_for_signal(@coop_signal)
+            if deadline && scheduler.virtual_time >= deadline
+              raise Phronomy::BackpressureError,
+                "ConcurrencyGate[#{@name}] timed out waiting for a free slot (cap: #{@max})"
+            end
+          else # :wait
+            scheduler.wait_for_signal(@coop_signal)
+          end
+        end
+      end
+
+      def _acquire_slot_threaded(on_full:, timeout:)
+        deadline = timeout ? (Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout) : nil
+
+        @mutex.synchronize do
+          loop do
+            if @count < @max
+              @count += 1
+              return
+            end
+
+            case on_full
+            when :reject
+              raise Phronomy::BackpressureError,
+                "ConcurrencyGate[#{@name}] at capacity (#{@max}); " \
+                "increase max_concurrent_#{@name}_tasks or retry later"
+            when :timeout
+              remaining = deadline ? (deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)) : nil
+              if remaining && remaining <= 0
+                raise Phronomy::BackpressureError,
+                  "ConcurrencyGate[#{@name}] timed out waiting for a free slot (cap: #{@max})"
+              end
+              @cond.wait(@mutex, remaining || nil)
+              # re-check deadline after wakeup
+              if deadline && Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
+                raise Phronomy::BackpressureError,
+                  "ConcurrencyGate[#{@name}] timed out waiting for a free slot (cap: #{@max})"
+              end
+            else # :wait
+              @cond.wait(@mutex)
+            end
+          end
+        end
+      end
+
+      def _release_slot
+        scheduler = Phronomy::Runtime::Scheduler.current
+        if scheduler && @coop_signal
+          @count -= 1
+          scheduler.raise_signal(@coop_signal)
+        else
+          @mutex.synchronize do
+            @count -= 1
+            @cond.signal
+          end
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/concurrency/deadline.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Concurrency
+    # A point in time used as an upper bound for an operation.
+    #
+    # Uses the monotonic clock (+Process::CLOCK_MONOTONIC+) internally to avoid
+    # skew from NTP adjustments or DST transitions.
+    #
+    # @example Create a 30-second deadline and check remaining time
+    #   deadline = Phronomy::Concurrency::Deadline.in(30)
+    #   sleep 1
+    #   deadline.remaining_seconds   # => ~29.0
+    #   deadline.expired?            # => false
+    class Deadline
+      # Creates a deadline that expires +seconds+ from now.
+      #
+      # @param seconds [Numeric] seconds from now until expiry
+      # @return [Deadline]
+      # @api private
+      def self.in(seconds)
+        new(Process.clock_gettime(Process::CLOCK_MONOTONIC) + seconds)
+      end
+
+      # @param monotonic_at [Float] absolute monotonic timestamp of expiry
+      # @api private
+      def initialize(monotonic_at)
+        @monotonic_at = monotonic_at
+      end
+
+      # Returns +true+ when the deadline has passed.
+      # @return [Boolean]
+      # @api private
+      def expired?
+        Process.clock_gettime(Process::CLOCK_MONOTONIC) >= @monotonic_at
+      end
+
+      # Seconds remaining until expiry.  Returns 0 when already expired.
+      # @return [Float]
+      # @api private
+      def remaining_seconds
+        remaining = @monotonic_at - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        [remaining, 0.0].max
+      end
+
+      # Attaches this deadline to a {CancellationToken} by cancelling the token
+      # when the deadline expires.  Uses the Runtime timer queue (a single
+      # background thread shared by all deadlines) instead of spawning one thread
+      # per deadline.
+      #
+      # @param token [CancellationToken]
+      # @param timer_queue [Runtime::TimerQueue, nil] queue to register with;
+      #   defaults to +Phronomy::Runtime.instance.timer_queue+
+      # @return [self]
+      # @api private
+      def attach_to(token, timer_queue: Phronomy::Runtime.instance.timer_queue)
+        seconds = remaining_seconds
+        return self if seconds <= 0
+
+        timer_queue.schedule(seconds: seconds) { token.cancel! }
+        self
+      end
+    end
+  end
+end

data/lib/phronomy/{runtime → concurrency}/gate_registry.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Phronomy
-  class Runtime
+  module Concurrency
     # Lazy cache of {ConcurrencyGate} instances, keyed by resource name.
     #
     # Gate concurrency caps are read from {Phronomy::Configuration} when a gate

data/lib/phronomy/{runtime → concurrency}/pool_registry.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Phronomy
-  class Runtime
+  module Concurrency
     # Registry and lifecycle manager for {BlockingAdapterPool} instances.
     #
     # Maintains one unnamed "default" pool (accessed via {#default_pool}) and

data/lib/phronomy/context.rb

@@ -5,14 +5,8 @@ module Phronomy
   # context assembly.
   #
   # Sub-modules are auto-loaded by Zeitwerk:
-  #   Phronomy::Context::TokenEstimator
-  #   Phronomy::Context::TokenBudget
+  #   Phronomy::LlmContextWindow::TokenEstimator
+  #   Phronomy::LlmContextWindow::TokenBudget
   module Context
   end
 end
-
-require_relative "context/assembler"
-require_relative "context/context_version_cache"
-require_relative "context/trim_context"
-require_relative "context/trigger_context"
-require_relative "context/compaction_context"

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,6 +28,7 @@ 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
@@ -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,7 +3,7 @@
 module Phronomy
   # Singleton event loop that manages all FSMSession instances.
   #
-  # A single background thread reads from a global {Phronomy::AsyncQueue} and
+  # 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
@@ -72,7 +72,7 @@ module Phronomy
     end
 
     def initialize
-      @queue = Phronomy::AsyncQueue.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.
@@ -80,7 +80,7 @@ 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
@@ -129,8 +129,8 @@ 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 [Phronomy::AsyncQueue] 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 Phronomy::EventLoop.current?
@@ -141,7 +141,7 @@ module Phronomy
           "Phronomy::EventLoop.instance.post(...) instead."
       end
 
-      completion_queue = Phronomy::AsyncQueue.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,
@@ -194,7 +194,7 @@ module Phronomy
       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
       # The dispatch loop must always run in a real background thread.

data/lib/phronomy/invocation_context.rb

@@ -11,7 +11,7 @@ module Phronomy
   # @example Build a context for a new agent invocation
   #   ctx = Phronomy::InvocationContext.new(
   #     thread_id:         "conv-123",
-  #     cancellation_token: Phronomy::CancellationToken.timeout_after(30),
+  #     cancellation_token: Phronomy::Concurrency::CancellationToken.timeout_after(30),
   #     max_parallel_tools: 5
   #   )
   #   agent.invoke("Hello", invocation_context: ctx)
@@ -127,7 +127,7 @@ module Phronomy
     # @return [CancellationToken]
     # @api private
     def effective_cancellation_token
-      @cancellation_token || CancellationToken.new
+      @cancellation_token || Phronomy::Concurrency::CancellationToken.new
     end
 
     # Returns the cancellation token to use for an invocation, taking both the
@@ -144,7 +144,7 @@ module Phronomy
       return @cancellation_token if @cancellation_token
       return nil if @deadline.nil?
 
-      token = CancellationToken.new
+      token = Phronomy::Concurrency::CancellationToken.new
       @deadline.attach_to(token)
       token
     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/ruby_llm.rb

@@ -14,27 +14,33 @@ module Phronomy
     #     c.llm_adapter = Phronomy::LLMAdapter::RubyLLM.new
     #   end
     class RubyLLM < Base
-      # Delegates to +chat.ask(message)+.
+      # Delegates to +chat.ask(message)+ or +chat.complete+ when message is nil.
       #
-      # @param chat    [Object] RubyLLM chat session
-      # @param message [String] user message
-      # @param config  [Hash]   invocation config (not used directly by this impl)
+      # 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: {})
-        chat.ask(message)
+        message ? chat.ask(message) : chat.complete
       end
 
-      # Delegates to +chat.ask(message) { |chunk| block.call(chunk) }+.
+      # 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] user message
-      # @param config  [Hash]   invocation config
-      # @yield [chunk] streaming chunk forwarded from +chat.ask+
+      # @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)
-        chat.ask(message, &block)
+        message ? chat.ask(message, &block) : chat.complete(&block)
       end
     end
   end