phronomy 0.7.0 → 0.8.0

data/lib/phronomy/testing/fake_clock.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Testing
+    # A deterministic, manually-advanced clock for use in tests.
+    #
+    # Replaces real +Process.clock_gettime+ calls so that time-sensitive code
+    # can be tested without relying on wall-clock sleeps.
+    #
+    # @example
+    #   clock = Phronomy::Testing::FakeClock.new
+    #   clock.now        # => 0.0
+    #   clock.advance(5) # advance by 5 seconds
+    #   clock.now        # => 5.0
+    class FakeClock
+      # @return [Float] the current logical time in seconds since the epoch (t=0)
+      attr_reader :now
+
+      def initialize
+        @now = 0.0
+        @callbacks = [] # [[fire_at, block], ...]
+        @mutex = Mutex.new
+      end
+
+      # Advance the clock by +seconds+ and fire any registered callbacks whose
+      # deadline has passed.
+      #
+      # @param seconds [Numeric]
+      # @return [self]
+      # @api private
+      def advance(seconds)
+        @mutex.synchronize do
+          @now += seconds.to_f
+          fire_expired_callbacks!
+        end
+        self
+      end
+
+      # Register a one-shot callback that fires when the clock reaches +at+.
+      #
+      # @param at [Numeric] logical time to fire
+      # @yield called with no arguments when the clock reaches +at+
+      # @return [self]
+      # @api private
+      def at(at, &block)
+        @mutex.synchronize { @callbacks << [at.to_f, block] }
+        self
+      end
+
+      # Schedule a one-shot callback to fire after +seconds+ from the current
+      # logical time.  This is the same interface as {Runtime::TimerQueue#schedule}
+      # so that a +FakeClock+ can be passed as a +timer_queue:+ argument in tests.
+      #
+      # @param seconds [Numeric] delay in logical seconds
+      # @yield called when the clock reaches the scheduled time
+      # @return [self]
+      # @api private
+      def schedule(seconds:, &block)
+        at(@now + seconds.to_f, &block)
+      end
+
+      # Returns the number of pending (un-fired) callbacks.
+      # @return [Integer]
+      # @api private
+      def pending_callbacks
+        @mutex.synchronize { @callbacks.size }
+      end
+
+      # Returns the logical time of the next pending callback, or +nil+ if
+      # there are no pending callbacks.
+      #
+      # @return [Float, nil]
+      # @api private
+      def next_timer_at
+        @mutex.synchronize { @callbacks.min_by { |(t, _)| t }&.first }
+      end
+
+      # Advance the clock exactly to the next pending callback and fire it.
+      # Raises +RuntimeError+ when there are no pending callbacks.
+      #
+      # @return [self]
+      # @api private
+      def advance_to_next_timer
+        target = next_timer_at
+        raise "No pending timers to advance to" unless target
+
+        advance(target - @now)
+      end
+
+      # Returns descriptive entries for all pending callbacks.
+      # Used by {Phronomy::Runtime::FakeScheduler#pending_timers}.
+      #
+      # @return [Array<Hash>] each entry: +{ fire_at:, description: nil }+
+      # @api private
+      def pending_timer_entries
+        @mutex.synchronize do
+          @callbacks.sort_by { |(t, _)| t }.map { |(t, _)| {fire_at: t, description: nil} }
+        end
+      end
+
+      private
+
+      def fire_expired_callbacks!
+        fired, @callbacks = @callbacks.partition { |(t, _)| t <= @now }
+        fired.sort_by { |(t, _)| t }.each { |(_, cb)| cb.call }
+      end
+    end
+  end
+end

data/lib/phronomy/testing/fake_scheduler.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Testing
+    # A deterministic event dispatcher for use in tests.
+    #
+    # Wraps a {Thread::Queue} and dispatches events one at a time via {#tick}
+    # or drains all pending events via {#tick_until_idle}.  Tests can inspect
+    # queue depth and verify event ordering without wall-clock sleeps.
+    #
+    # @example
+    #   scheduler = Phronomy::Testing::FakeScheduler.new
+    #   scheduler.post(:a)
+    #   scheduler.post(:b)
+    #   scheduler.queue_depth   # => 2
+    #   scheduler.tick          # dispatches :a
+    #   scheduler.queue_depth   # => 1
+    #   scheduler.tick_until_idle
+    #   scheduler.dispatched    # => [:a, :b]
+    class FakeScheduler
+      # @return [Array] all events dispatched so far (in order)
+      attr_reader :dispatched
+
+      def initialize
+        @queue = Thread::Queue.new
+        @dispatched = []
+        @handlers = {}
+      end
+
+      # Enqueue an event for later dispatch.
+      #
+      # @param event [Object]
+      # @return [self]
+      # @api private
+      def post(event)
+        @queue.push(event)
+        self
+      end
+
+      # Dispatch the next queued event.
+      # Calls the registered handler (if any) and records the event.
+      # Returns the dispatched event, or +nil+ if the queue is empty.
+      #
+      # @return [Object, nil]
+      # @api private
+      def tick
+        return nil if @queue.empty?
+
+        event = begin
+          @queue.pop(true)
+        rescue
+          nil
+        end
+        return nil unless event
+
+        @dispatched << event
+        handler = @handlers[event.class] || @handlers[:any]
+        handler&.call(event)
+        event
+      end
+
+      # Dispatch events until the queue is empty.
+      # Bounded by +max_ticks+ to prevent infinite loops.
+      #
+      # @param max_ticks [Integer]
+      # @return [Integer] number of events dispatched
+      # @api private
+      def tick_until_idle(max_ticks: 1000)
+        count = 0
+        while !@queue.empty? && count < max_ticks
+          tick
+          count += 1
+        end
+        count
+      end
+
+      # Returns the number of events waiting to be dispatched.
+      # @return [Integer]
+      # @api private
+      def queue_depth
+        @queue.size
+      end
+
+      # Register a handler block for events of the given class.
+      # Use +:any+ to handle all event types.
+      #
+      # @param klass [Class, :any]
+      # @yield [event]
+      # @return [self]
+      # @api private
+      def on(klass, &block)
+        @handlers[klass] = block
+        self
+      end
+
+      # Returns true when the queue is empty.
+      # @return [Boolean]
+      # @api private
+      def idle?
+        @queue.empty?
+      end
+    end
+  end
+end

data/lib/phronomy/testing/scheduler_helpers.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Testing
+    # RSpec helper module that provides a deterministic {Runtime} backed by
+    # {Phronomy::Runtime::FakeScheduler}.
+    #
+    # Include this module in your RSpec describe/context blocks and call
+    # {#with_fake_scheduler} to run a block of code inside a fully
+    # synchronous, event-logged runtime.
+    #
+    # @example Basic usage (no clock)
+    #   include Phronomy::Testing::SchedulerHelpers
+    #
+    #   it "records completed events" do
+    #     with_fake_scheduler do |sched|
+    #       Phronomy::Runtime.instance.spawn(name: "my-task") { 42 }
+    #       expect(sched.event_log.map { |e| e[:type] }).to include(:completed)
+    #     end
+    #   end
+    #
+    # @example With a FakeClock
+    #   include Phronomy::Testing::SchedulerHelpers
+    #
+    #   it "surfaces pending timers" do
+    #     clock = Phronomy::Testing::FakeClock.new
+    #     with_fake_scheduler(clock: clock) do |sched|
+    #       clock.schedule(seconds: 5) { :fired }
+    #       expect(sched.pending_timers.first[:fire_at]).to eq(5.0)
+    #     end
+    #   end
+    module SchedulerHelpers
+      # Run +block+ with a {Phronomy::Runtime} that uses
+      # {Phronomy::Runtime::FakeScheduler}.
+      #
+      # The global runtime is replaced for the duration of the block and
+      # restored afterwards, whether the block raises or not.
+      #
+      # @param clock [Phronomy::Testing::FakeClock, nil]
+      #   Optional fake clock to inject into the scheduler for timer support
+      #   and event timestamping.
+      # @yield [scheduler, clock] the {Runtime::FakeScheduler} and the clock
+      # @return [Object] the return value of the block
+      # @api private
+      def with_fake_scheduler(clock: nil)
+        scheduler = Phronomy::Runtime::FakeScheduler.new
+        scheduler.clock = clock if clock
+        runtime = Phronomy::Runtime.new(scheduler: scheduler)
+        original = Phronomy::Runtime.instance
+        Phronomy::Runtime.instance = runtime
+        begin
+          yield scheduler, clock
+        ensure
+          Phronomy::Runtime.instance = original
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/testing.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Phronomy
+  # Test helpers for deterministic, timer-independent testing.
+  #
+  # @example
+  #   require "phronomy/testing"
+  #   clock = Phronomy::Testing::FakeClock.new
+  #   scheduler = Phronomy::Testing::FakeScheduler.new
+  module Testing
+  end
+end

data/lib/phronomy/tool/base.rb

@@ -68,6 +68,7 @@ module Phronomy
         # Returns nested schema definitions registered via .param(properties: ...).
         # @return [Hash{Symbol => Hash}]
         # @api public
+        # mutant:disable - neutral failure: unparser round-trip produces different source
         def param_schemas
           @param_schemas ||= {}
         end
@@ -76,6 +77,7 @@ module Phronomy
 
         # Recursively normalises a properties hash so all keys are Symbols and
         # each spec has a :type key.
+        # mutant:disable
         def normalize_nested_schema(props)
           props.transform_keys(&:to_sym).transform_values do |spec|
             s = spec.transform_keys(&:to_sym)
@@ -91,12 +93,45 @@ module Phronomy
         # the Workflow/Guardrail layer).
         # @param value [Symbol] e.g. :read_only, :write, :admin
         # @api public
+        # mutant:disable - neutral failure: unparser round-trip produces different source
         def scope(value = nil)
           return @scope if value.nil?
 
           @scope = value
         end
 
+        # Sets or reads the execution mode for this tool.
+        #
+        # Execution mode is the concurrency contract declaration for the tool.
+        # In Phronomy's non-preemptive, cooperative concurrency model it controls
+        # which runtime resource is used to dispatch the tool:
+        #
+        # | Mode | Dispatcher | Constraint |
+        # |------|-----------|------------|
+        # | +:cooperative+ | +Runtime.instance.spawn+ (scheduler task) | *Must not* block the scheduler thread; use only for in-memory computation |
+        # | +:blocking_io+ | {Phronomy::Concurrency::BlockingAdapterPool} (bounded thread pool) | **Default**. Safe for all blocking I/O (HTTP, DB, file) |
+        # | +:cpu_bound+ | Falls back to +:blocking_io+ + emits a warning | No dedicated process pool yet; use +:blocking_io+ explicitly to suppress the warning |
+        # | +:external_process+ | Falls back to +:blocking_io+ | No process manager yet |
+        #
+        # Tools that perform network calls, file I/O, or database queries should use
+        # +:blocking_io+ (the default).  Tools that only perform in-memory computation
+        # may declare +:cooperative+ for lower overhead.
+        #
+        # @param value [Symbol, nil] when nil, returns the current value
+        # @return [Symbol] the current execution mode (default :blocking_io)
+        # @api public
+        # mutant:disable
+        def execution_mode(value = nil)
+          return @execution_mode || :blocking_io if value.nil?
+
+          valid = %i[cooperative blocking_io cpu_bound external_process]
+          unless valid.include?(value)
+            raise ArgumentError, "execution_mode must be one of #{valid.inspect}, got #{value.inspect}"
+          end
+
+          @execution_mode = value
+        end
+
         # Configures error-handling behavior when +execute+ raises an unexpected error.
         #
         # @param behavior [Symbol]
@@ -130,6 +165,7 @@ module Phronomy
         #   :coerce                 — attempt type coercion (e.g. "42" → 42 for :integer);
         #                             falls back to :return_error when coercion is not possible.
         # @api public
+        # mutant:disable - neutral failure: unparser round-trip produces different source
         def on_schema_error(behavior = nil)
           return @on_schema_error || :return_error if behavior.nil?
 
@@ -139,12 +175,41 @@ module Phronomy
         # Configures whether human approval is required before executing this tool.
         # @param value [Boolean]
         # @api public
+        # mutant:disable - neutral failure: unparser round-trip produces different source
         def requires_approval(value = nil)
           return @requires_approval || false if value.nil?
 
           @requires_approval = value
         end
 
+        # Marks one or more parameter names as sensitive so their values are
+        # replaced with +"[REDACTED]"+ in log and trace output.
+        #
+        # @param names [Array<Symbol>] parameter names to redact
+        # @return [Array<Symbol>] the full list of redacted param names
+        # @api public
+        # mutant:disable
+        def redact_params(*names)
+          if names.empty?
+            parent = superclass.respond_to?(:redact_params) ? superclass.redact_params : []
+            ((@redacted_params || []) + parent).uniq
+          else
+            @redacted_params = ((@redacted_params || []) + names.map(&:to_sym)).uniq
+          end
+        end
+
+        # Sets a per-tool maximum result size (in characters).
+        # Overrides the global +Phronomy.configuration.tool_result_max_size+ when set.
+        # Set to +nil+ to inherit the global limit.
+        #
+        # @param value [Integer, nil]
+        # @api public
+        def max_result_size(value = :__unset__)
+          return @max_result_size if value == :__unset__
+
+          @max_result_size = value
+        end
+
         # Registers a retry policy for one or more exception classes.
         #
         # When the tool raises one of the listed exception classes, it will be
@@ -170,6 +235,7 @@ module Phronomy
         # Returns all retry policies registered on this tool class.
         # @return [Array<Hash>]
         # @api public
+        # mutant:disable - neutral failure: unparser round-trip produces different source
         def retry_policies
           @retry_policies || []
         end
@@ -178,6 +244,7 @@ module Phronomy
         # Defaults to Kernel#sleep.
         # @return [#call]
         # @api private
+        # mutant:disable - neutral failure: unparser round-trip produces different source
         def _sleep_proc
           @_sleep_proc || method(:sleep)
         end
@@ -190,12 +257,18 @@ module Phronomy
       # Returns the function name exposed to the LLM.
       # Uses the class-level tool_name if set; otherwise falls back to RubyLLM's
       # automatic conversion (CamelCase → snake_case, strips trailing "_tool").
+      # mutant:disable - neutral failure: unparser round-trip produces different source
       def name
         self.class.tool_name || super
       end
 
       # Returns the JSON Schema for this tool's parameters.
       # Injects "enum" entries for any param declared with enum: [...].
+      # mutant:disable - genuine equivalent mutations:
+      #   1. `|| schema.dig(:properties)`: dead code because RubyLLM::Tool always returns a
+      #      string-keyed hash; schema.dig(:properties) is always nil in practice.
+      #   2. `return schema unless properties` guard: dead code when schema is non-nil because
+      #      RubyLLM::Tool always includes a "properties" key when parameters are declared.
       def params_schema
         schema = super
         return schema if schema.nil?
@@ -245,10 +318,11 @@ module Phronomy
       #   5. On persistent failure, apply on_error policy.
       #
       # @param args               [Hash]
-      # @param cancellation_token [Phronomy::CancellationToken, nil] optional; takes precedence over the thread-local token
+      # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil] optional; takes precedence over the thread-local token
       # @api public
+      # mutant:disable
       def call(args, cancellation_token: nil)
-        ct = cancellation_token || Thread.current[:phronomy_cancellation_token]
+        ct = cancellation_token
         ct&.raise_if_cancelled!
         validated_args, schema_error = validate_and_coerce(args)
         if schema_error
@@ -261,7 +335,8 @@ module Phronomy
           end
         end
         validated_args = validated_args.merge(cancellation_token: ct) if ct && execute_accepts_cancellation_token?
-        with_tool_retry { super(validated_args) }
+        result = with_tool_retry { super(validated_args) }
+        truncate_result_if_needed(result)
       rescue Phronomy::ToolError
         raise
       rescue Phronomy::CancellationError
@@ -281,12 +356,34 @@ module Phronomy
         end
       end
 
+      # Invokes this tool asynchronously and returns a {Phronomy::Task}.
+      #
+      # Routing is governed by the class-level {.execution_mode} setting.
+      # Delegates to {Phronomy::Agent::ToolExecutor.call_async} which is the single
+      # place in the framework that applies the execution-mode routing rules.
+      #
+      # @param args               [Hash]
+      # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil]
+      # @return [#await]
+      # @api public
+      # mutant:disable
+      def call_async(args, cancellation_token: nil)
+        Phronomy::Agent::ToolExecutor.call_async(
+          tool: self,
+          args: args,
+          cancellation_token: cancellation_token
+        )
+      end
+
       # Instance method accessor — delegates to the class-level flag.
       def requires_approval
         self.class.requires_approval
       end
 
       # Instance method for requires_approval? (convenience accessor).
+      # mutant:disable - genuine equivalent: self.requires_approval delegates to
+      # self.class.requires_approval via the instance method defined above, so
+      # both expressions produce the same value.
       def requires_approval?
         self.class.requires_approval
       end
@@ -316,16 +413,57 @@ module Phronomy
 
       # Returns true when the #execute method declares a +cancellation_token:+
       # keyword parameter, indicating it opts into cooperative cancellation.
+      # mutant:disable
       def execute_accepts_cancellation_token?
-        method(:execute).parameters.any? do |type, name|
+        method(:execute).parameters.any? do |type, name| # mutant:disable
           name == :cancellation_token && %i[key keyreq].include?(type)
         end
       end
 
+      # Truncates the result string when it exceeds the configured maximum size.
+      # Uses the per-tool limit first, then the global configuration limit.
+      # Returns the original result when no limit is configured.
+      def truncate_result_if_needed(result)
+        max = self.class.max_result_size || Phronomy.configuration.tool_result_max_size
+        return result unless max && result.respond_to?(:length) && result.length > max
+
+        msg = "[Phronomy] Tool #{self.class.name} result truncated " \
+              "(#{result.length} chars > #{max} limit)"
+        if Phronomy.configuration.logger
+          Phronomy.configuration.logger.warn(msg)
+        else
+          warn msg
+        end
+        "#{result[0, max]}...[truncated]"
+      end
+
+      # Returns a copy of +args+ with redacted parameter values replaced by
+      # +"[REDACTED]"+.  Used for logging and tracing.
+      # @param args [Hash]
+      # @return [Hash]
+      # @api private
+      def redacted_args(args)
+        redacted = self.class.redact_params
+        return args if redacted.empty?
+
+        args.each_with_object({}) do |(k, v), h|
+          h[k] = redacted.include?(k.to_sym) ? "[REDACTED]" : v
+        end
+      end
+
       # Executes the given block inside a retry loop driven by the class-level
       # retry_policies. Each policy matches by exception class; the first matching
       # policy governs the wait and retry count. Raises immediately when no policy
       # covers the exception or when all retries are exhausted.
+      # mutant:disable - genuine equivalent mutations:
+      #   1. `if policies.empty?; return yield; end` early-return variants (nil, false, block
+      #      removal): behavior is identical because when policies is empty, yield is still
+      #      called inside begin/rescue, any exception is re-raised (policy=nil, condition
+      #      false), and successful returns propagate the same value either way.
+      #   2. `p[:exceptions].any?` vs `p.fetch(:exceptions).any?`: :exceptions key is always
+      #      present (set unconditionally by .retry_on), so fetch/[] are equivalent.
+      #   3. `policy[:times]`, `policy[:wait]`, `policy[:base]` vs `.fetch(...)`: same reason
+      #      as #2 — all keys are always set by .retry_on.
       def with_tool_retry
         policies = self.class.retry_policies
         return yield if policies.empty?
@@ -371,14 +509,21 @@ module Phronomy
       # @param args [Hash] raw args passed to #call (string or symbol keys)
       # @return [Array(Hash, String|nil)] [possibly_coerced_args, error_message_or_nil]
       # @api public
+      # mutant:disable
       def validate_and_coerce(args)
+        # mutant:disable - genuine equivalents:
+        #   1. `return [args, nil]` vs `return [args]`: Ruby multiple assignment
+        #      fills nil for missing elements, so both are identical to callers.
+        #   2. `self.class.parameters` vs `self.parameters`: RubyLLM::Tool exposes
+        #      `parameters` as both a class method and an instance method that
+        #      delegates to the class method, so both return the same value.
         return [args, nil] if self.class.parameters.empty?
 
         normalized = (args || {}).transform_keys(&:to_sym)
         coerce_mode = self.class.on_schema_error == :coerce
         result = {}
 
-        self.class.parameters.each do |name, param|
+        self.class.parameters.each do |name, param| # mutant:disable
           value = normalized[name]
           if value.nil?
             # Return a descriptive error for missing required params so the LLM
@@ -415,12 +560,12 @@ module Phronomy
 
         # Reject any keys not covered by declared parameters to prevent silent
         # parameter injection (e.g. via prompt injection).
-        extra = normalized.keys - self.class.parameters.keys
+        extra = normalized.keys - self.class.parameters.keys # mutant:disable
         unless extra.empty?
           return [nil, "unknown parameter(s): #{extra.inspect}"]
         end
 
-        [result, nil]
+        [result, nil] # mutant:disable
       end
 
       # Converts the internal normalized nested schema (from param_schemas) to
@@ -430,6 +575,7 @@ module Phronomy
       # @param nested [Hash{Symbol=>Hash}] normalized schema from param_schemas
       # @return [Hash{String=>Hash}] JSON Schema properties
       # @api public
+      # mutant:disable
       def nested_schema_to_json_schema(nested)
         nested.each_with_object({}) do |(prop_name, spec), acc|
           entry = {"type" => spec[:type].to_s}
@@ -447,6 +593,7 @@ module Phronomy
       # @param properties [Hash{Symbol=>Hash}] nested schema from param_schemas
       # @param path       [String]          dot-separated field path for error messages
       # @api public
+      # mutant:disable
       def validate_nested_object(value, properties, path)
         return "field '#{path}' must be an object (Hash)" unless value.is_a?(Hash)
 
@@ -484,6 +631,7 @@ module Phronomy
       # @param value         [Object]
       # @param declared_type [Symbol, String]  e.g. :string, :integer, :number, :boolean, :array, :object
       # @api public
+      # mutant:disable
       def type_error(value, declared_type)
         return nil if value.nil?
 
@@ -506,6 +654,7 @@ module Phronomy
 
       # Attempts to coerce +value+ to +declared_type+.
       # Returns [coerced_value, nil] on success, [nil, error_message] on failure.
+      # mutant:disable
       def coerce_value(value, declared_type)
         return [value, nil] if value.nil?