phronomy 0.7.0 → 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/concurrency/gate_registry.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Concurrency
+    # Lazy cache of {ConcurrencyGate} instances, keyed by resource name.
+    #
+    # Gate concurrency caps are read from {Phronomy::Configuration} when a gate
+    # is first accessed; subsequent calls return the cached instance.  Call
+    # {#reset} to drop the cache and force a rebuild on the next access.
+    # @api private
+    class GateRegistry
+      GATE_CONFIG_MAP = {
+        agent: :max_concurrent_agent_tasks,
+        tool: :max_concurrent_tool_tasks,
+        workflow: :max_concurrent_workflow_tasks,
+        llm: :max_concurrent_llm_calls,
+        rag: :max_concurrent_rag_fetches,
+        vector: :max_concurrent_vector_searches
+      }.freeze
+      private_constant :GATE_CONFIG_MAP
+
+      def initialize
+        @mutex = Mutex.new
+        @gates = {}
+      end
+
+      # Returns (or lazily creates) the gate for +name+.
+      # @param name [Symbol]
+      # @return [ConcurrencyGate]
+      # @api private
+      def get(name)
+        @mutex.synchronize { @gates[name] ||= _build(name) }
+      end
+
+      # Drops the cached gate for +name+ so the next {#get} rebuilds it.
+      # @param name [Symbol]
+      # @return [void]
+      # @api private
+      def reset(name)
+        @mutex.synchronize { @gates.delete(name) }
+      end
+
+      private
+
+      def _build(name)
+        config_key = GATE_CONFIG_MAP[name]
+        max = config_key ? Phronomy.configuration.public_send(config_key) : nil
+        ConcurrencyGate.new(max_concurrent: max, name: name)
+      end
+    end
+  end
+end

data/lib/phronomy/concurrency/pool_registry.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Concurrency
+    # Registry and lifecycle manager for {BlockingAdapterPool} instances.
+    #
+    # Maintains one unnamed "default" pool (accessed via {#default_pool}) and
+    # an arbitrary number of named pools (accessed via {#named_pool}).
+    # All pools are shut down together by {#shutdown}.
+    # @api private
+    class PoolRegistry
+      def initialize
+        @mutex = Mutex.new
+        @pools = {}
+        @default = nil
+      end
+
+      # Returns (or lazily creates) the unnamed default pool.
+      # @param pool_size  [Integer]
+      # @param queue_size [Integer]
+      # @return [BlockingAdapterPool]
+      # @api private
+      def default_pool(pool_size: 10, queue_size: 100)
+        @default ||= BlockingAdapterPool.new(
+          name: :default,
+          pool_size: pool_size,
+          queue_size: queue_size
+        )
+      end
+
+      # Returns (or lazily creates) a named pool.
+      # @param name      [Symbol, String]
+      # @param size      [Integer]
+      # @param queue_size [Integer]
+      # @return [BlockingAdapterPool]
+      # @api private
+      def named_pool(name, size: 10, queue_size: 100)
+        @mutex.synchronize do
+          @pools[name.to_sym] ||= BlockingAdapterPool.new(
+            name: name,
+            pool_size: size,
+            queue_size: queue_size
+          )
+        end
+      end
+
+      # Shuts down the default pool and all named pools.
+      # @return [void]
+      # @api private
+      def shutdown
+        @default&.shutdown
+        pools = @mutex.synchronize { @pools.values.dup }
+        pools.each(&:shutdown)
+      end
+    end
+  end
+end

data/lib/phronomy/configuration.rb

@@ -61,12 +61,154 @@ module Phronomy
     #   Phronomy.configure { |c| c.state_store = Phronomy::StateStore::InMemory.new }
     attr_accessor :state_store
 
+    # Maximum byte length of a tool result returned to the LLM.
+    # When a tool returns a String longer than this limit, the string is truncated
+    # and a warning is logged.  Set to +nil+ (default) to disable truncation.
+    # @example
+    #   Phronomy.configure { |c| c.tool_result_max_size = 8192 }
+    attr_accessor :tool_result_max_size
+
+    # LLM adapter used by Agent::Base to perform LLM calls.
+    # Must be an instance of a class that inherits from
+    # {Phronomy::LLMAdapter::Base}.  Defaults to
+    # {Phronomy::LLMAdapter::RubyLLM} which delegates to +chat.ask+ via
+    # {BlockingAdapterPool}.
+    # Set to a custom adapter to swap in an alternative LLM client without
+    # changing any agent code.
+    # @example
+    #   Phronomy.configure { |c| c.llm_adapter = MyAsyncLLMAdapter.new }
+    attr_accessor :llm_adapter
+
+    # Default backpressure strategy for {BlockingAdapterPool#submit} when the
+    # queue is full.  One of +:wait+ (block until a slot is available),
+    # +:raise+ (raise {Phronomy::BackpressureError}), or +:timeout+ (raise
+    # {Phronomy::TimeoutError} after +backpressure_timeout+ seconds).
+    # @return [:wait, :raise, :timeout]
+    attr_accessor :backpressure
+
+    # Seconds to wait before raising {Phronomy::TimeoutError} when
+    # +backpressure+ is +:timeout+.
+    # @return [Numeric, nil]
+    attr_accessor :backpressure_timeout
+
+    # Warn when an event spends longer than this many seconds waiting in the
+    # EventLoop queue before being dispatched (starvation detection).
+    # Set to +nil+ to disable the warning.
+    # @return [Numeric, nil]
+    attr_accessor :event_loop_starvation_threshold_seconds
+
+    # Warn when processing a single event on the EventLoop thread takes longer
+    # than this many seconds (long-running task / blocking-on-loop detection).
+    # Set to +nil+ to disable the warning.
+    # @return [Numeric, nil]
+    attr_accessor :event_loop_dispatch_threshold_seconds
+
+    # When true, enables all blocking operation diagnostics (Issue #279).
+    # Equivalent to setting all diagnostic thresholds to their defaults.
+    # @return [Boolean]
+    attr_accessor :scheduler_debug
+
+    # Wall-clock threshold (milliseconds) after which a task that has not
+    # yielded the scheduler emits a warning log.  nil disables the check.
+    # @return [Float, nil]
+    attr_accessor :blocking_detect_threshold_ms
+
+    # Maximum number of concurrent agent tasks (invoke_async calls in-flight).
+    # nil = unlimited (default).  When at capacity, behaviour is controlled by
+    # +backpressure+ (:wait, :raise/:reject, :timeout).
+    # @return [Integer, nil]
+    attr_accessor :max_concurrent_agent_tasks
+
+    # Maximum number of concurrent tool tasks (parallel tool calls in-flight).
+    # nil = unlimited (default).
+    # @return [Integer, nil]
+    attr_accessor :max_concurrent_tool_tasks
+
+    # Maximum number of concurrent workflow tasks.
+    # nil = unlimited (default).
+    # @return [Integer, nil]
+    attr_accessor :max_concurrent_workflow_tasks
+
+    # Maximum number of concurrent LLM calls in-flight.
+    # nil = unlimited (default).
+    # @return [Integer, nil]
+    attr_accessor :max_concurrent_llm_calls
+
+    # Upper bound on the number of streaming token chunks that may be buffered
+    # in the {AsyncQueue} used by {Agent#stream} before the LLM producer is
+    # throttled.  When nil (default), the queue is unbounded.
+    # @return [Integer, nil]
+    attr_accessor :stream_queue_max_size
+
+    # Maximum number of concurrent RAG knowledge-source fetches in-flight.
+    # nil = unlimited (default).
+    # @return [Integer, nil]
+    attr_accessor :max_concurrent_rag_fetches
+
+    # Maximum number of concurrent vector-store searches in-flight.
+    # nil = unlimited (default).
+    # @return [Integer, nil]
+    attr_accessor :max_concurrent_vector_searches
+
+    # Scheduler starvation threshold (milliseconds).
+    # When a task waits more than this many milliseconds after calling
+    # +runtime.yield+ before being resumed, the wait is counted as a starvation
+    # event.  Used by the fairness regression test and by the
+    # +tasks_waiting_over_threshold+ metric on {Phronomy::Runtime}.
+    # Default: 50ms.
+    # @return [Numeric]
+    attr_accessor :starvation_threshold_ms
+
+    # Scheduler backend to use for new {Phronomy::Runtime} instances.
+    #
+    # | Value | Scheduler | Typical use |
+    # |-------|-----------|-------------|
+    # | +:thread+ | {Runtime::ThreadScheduler} | **Default** — production-ready; one OS thread per task |
+    # | +:immediate+ | {Runtime::FakeScheduler} | Tests — tasks run synchronously, no extra threads |
+    # | +:fiber+ | {Runtime::DeterministicScheduler} (autorun) | **EXPERIMENTAL** — Fiber-based cooperative scheduler; do not use as production default |
+    # | +:cooperative+ | {Runtime::FakeScheduler} | **Deprecated** — alias for +:immediate+; do not use in new code |
+    #
+    # The default is +:thread+. The +:fiber+ backend remains experimental and opt-in;
+    # it will not become the default until integration test coverage is production grade
+    # and virtual-time/timeout semantics are fully resolved (see Issues #350, #347, #348).
+    #
+    # When this setting is changed, the change only takes effect on the NEXT
+    # call to {Runtime.instance} that auto-creates a new instance (i.e. after the
+    # previous instance has been replaced or reset).  To replace the current
+    # instance immediately call +Phronomy::Runtime.instance = nil+ first.
+    #
+    # @return [:thread, :immediate, :fiber]
+    attr_accessor :runtime_backend
+
+    # When +true+, calling {Agent#invoke} from inside a scheduler task
+    # raises {SchedulerReentrancyError}.  When +false+ (default), a warning
+    # is logged instead so that existing callers have time to migrate.
+    # @return [Boolean]
+    attr_accessor :strict_runtime_guards
+
     def initialize
       @recursion_limit = 25
       @tracer = Phronomy::Tracing::NullTracer.new
       @trace_pii = false
       @event_loop = false
       @event_loop_stop_grace_seconds = 5
+      @llm_adapter = Phronomy::LLMAdapter::RubyLLM.new
+      @backpressure = :wait
+      @backpressure_timeout = nil
+      @event_loop_starvation_threshold_seconds = nil
+      @event_loop_dispatch_threshold_seconds = nil
+      @scheduler_debug = false
+      @blocking_detect_threshold_ms = nil
+      @max_concurrent_agent_tasks = nil
+      @max_concurrent_tool_tasks = nil
+      @max_concurrent_workflow_tasks = nil
+      @max_concurrent_llm_calls = nil
+      @stream_queue_max_size = nil
+      @max_concurrent_rag_fetches = nil
+      @max_concurrent_vector_searches = nil
+      @starvation_threshold_ms = 50
+      @runtime_backend = :thread
+      @strict_runtime_guards = false
     end
   end
 end

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"