phronomy 0.16.0 → 0.17.0

data/lib/phronomy/configuration.rb

@@ -3,191 +3,36 @@
 module Phronomy
   # Holds global configuration for the entire framework.
   # Configure via the Phronomy.configure block.
-  #
-  # @example
-  #   Phronomy.configure do |config|
-  #     config.default_model    = "claude-3-5-sonnet-20241022"
-  #     config.recursion_limit  = 50
-  #   end
   class Configuration
     STREAM_CALLBACK_ERROR_POLICIES = %i[report fail_task].freeze
-    private_constant :STREAM_CALLBACK_ERROR_POLICIES
+    RUNTIME_BACKENDS = %i[thread immediate fiber].freeze
+    private_constant :STREAM_CALLBACK_ERROR_POLICIES, :RUNTIME_BACKENDS
 
-    # Default LLM model name (nil delegates to RubyLLM default)
     attr_accessor :default_model
-
-    # Default embedding model name
     attr_accessor :default_embedding_model
-
-    # Tracer instance
     attr_accessor :tracer
-
-    # Global before_llm_input hook callable (Proc / lambda).
-    # Called before every LLM request across all agents.
-    # Receives a {Phronomy::Agent::LLMInputBuildContext}; must return a
-    # {Phronomy::Agent::LLMInputPatch} or nil to pass through unchanged.
     attr_accessor :before_llm_input
-
-    # Default output token reservation when an agent does not set max_output_tokens
-    # and the model registry value equals the context window (making it unusable
-    # as a per-request output reserve). Integer or nil.
     attr_accessor :default_output_reserve
-
-    # Recursion limit for graph execution (default: 25)
     attr_accessor :recursion_limit
-
-    # When true, agent LLM calls use {Phronomy::MultiAgent::ParallelToolChat}
-    # for concurrent tool dispatch within a single agent turn.
-    # Defaults to false.
-    #
-    # Previously, this was automatically enabled when +event_loop+ was true.
-    # As of Phase 3, +parallel_tool_execution+ is a separate setting that must
-    # be explicitly enabled.
-    # @example
-    #   Phronomy.configure { |c| c.parallel_tool_execution = true }
-    # @return [Boolean]
     attr_accessor :parallel_tool_execution
-
-    # When true, user input and LLM output are recorded in trace spans.
-    # Defaults to false; set to true only in environments where PII capture is acceptable.
-    # Set to false in privacy-sensitive environments to prevent PII from reaching
-    # the tracing backend (OTel, Langfuse, etc.).
     attr_accessor :trace_pii
-
-    # Optional logger for framework diagnostic messages (e.g. unreachable-state warnings).
-    # Must respond to +#warn(message)+.  When nil (default), messages are written to +$stderr+
-    # via +Kernel#warn+.
-    # @example
-    #   Phronomy.configure { |c| c.logger = Rails.logger }
     attr_accessor :logger
-
-    # Grace period (in seconds) before the EventLoop background thread is force-killed
-    # after a cooperative stop request.  Applies both to the overall thread join
-    # and to the drain-and-cancel phase when +stop(drain: true)+ is used.
-    # Default: 5 seconds.
-    # @see Phronomy::EventLoop#stop
     attr_accessor :event_loop_stop_grace_seconds
-
-    # Global state store for workflow persistence.
-    # When set, WorkflowRunner routes all state reads and writes through this store.
-    # Must be an instance of a class that inherits from Phronomy::StateStore::Base.
-    # Defaults to +nil+ (no persistence — state lives only for the duration of invoke).
-    # @example
-    #   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
-
-    # 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
-
-    # Determines how an unhandled Application exception from a terminal stream
-    # callback affects the Task returned by Agent#stream_async or
-    # Agent#approve_async.
-    #
-    # +:report+ logs the callback failure and preserves the Agent result.
-    # +:fail_task+ logs the callback failure and fails the current Task with
-    # {Phronomy::StreamCallbackError}. Neither policy terminates EventLoop.
-    #
-    # Default: +:report+.
-    # @return [:report, :fail_task]
     attr_reader :stream_callback_error_policy
-
-    # Number of OS worker threads in the default {BlockingAdapterPool}.
-    # All LLM calls, MCP tool calls, and other blocking I/O share this pool.
-    # Increase for higher LLM/tool throughput; decrease to limit
-    # concurrency (e.g. to stay within a provider's rate limit).
-    # Default: 10.
-    # @return [Integer]
     attr_accessor :blocking_io_pool_size
-
-    # Maximum number of operations that may wait in the {BlockingAdapterPool}
-    # queue before {Phronomy::BackpressureError} is raised (on_full: :raise) or
-    # the caller blocks (on_full: :wait, the default). Default: 100.
-    # @return [Integer]
     attr_accessor :blocking_io_queue_size
-
-    # Worker count for Tool authorization evaluation. The named pool is owned
-    # by Runtime#pool(:authorization) and shares PoolRegistry lifecycle.
-    # @return [Integer]
     attr_accessor :authorization_pool_size
-
-    # Maximum queued Tool authorization evaluations.
-    # @return [Integer]
     attr_accessor :authorization_queue_size
-
-    # Operation-wide deadline for approval_facts, requires_approval callables,
-    # and Agent#tool_approval_policy. Timeout fails closed to Human approval.
-    # @return [Numeric]
     attr_accessor :authorization_timeout
-
-    # 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_reader :runtime_backend
     attr_accessor :strict_runtime_guards
 
     def stream_callback_error_policy=(value)
@@ -200,6 +45,18 @@ module Phronomy
       @stream_callback_error_policy = value
     end
 
+    # Scheduler backend used for newly-created Runtime instances.
+    # Supported values are :thread, :immediate, and :fiber.
+    def runtime_backend=(value)
+      value = value.to_sym if value.respond_to?(:to_sym)
+      unless RUNTIME_BACKENDS.include?(value)
+        allowed = RUNTIME_BACKENDS.map(&:inspect).join(", ")
+        raise Phronomy::ConfigurationError,
+          "runtime_backend must be one of: #{allowed}"
+      end
+      @runtime_backend = value
+    end
+
     def initialize
       @recursion_limit = 25
       @tracer = Phronomy::Tracing::NullTracer.new

data/lib/phronomy/engine/concurrency/cancellation_token.rb

@@ -2,90 +2,33 @@
 
 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)
+    # Cooperative cancellation token for Agent/Tool work.
     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]
+      # Creates a token that expires after +seconds+ measured with the monotonic clock.
       # @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.
+      # @param monotonic_deadline [Float, nil] internal monotonic timestamp.
       # @api public
-      # mutant:disable - removing @cancelled = false is equivalent because nil is falsey
-      def initialize(deadline: nil, monotonic_deadline: nil)
+      def initialize(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
-      # {Phronomy::Concurrency::CancellationScope#deadline_in}, which registers
-      # a timer via {Runtime#timer_queue} and calls {#cancel!} on expiry — this
-      # fires all +on_cancel+ callbacks automatically.  {.timeout_after} is a
-      # lightweight alternative that uses lazy clock comparison only and does
-      # NOT trigger callbacks on expiry.
-      #
-      # @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
@@ -99,14 +42,11 @@ module Phronomy
         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
@@ -114,28 +54,15 @@ module Phronomy
         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