phronomy 0.7.0 → 0.7.1

data/lib/phronomy/task_group.rb

@@ -0,0 +1,265 @@
+# frozen_string_literal: true
+
+module Phronomy
+  # Manages a bounded set of concurrent {Task}s with structured concurrency.
+  #
+  # Enforces an upper bound on simultaneously running tasks (+limit+).
+  # When the limit is reached, {#spawn} blocks the caller until a slot
+  # becomes available.  Results are always returned in the order tasks
+  # were spawned, regardless of completion order.
+  #
+  # A configurable +failure_policy+ controls how errors propagate:
+  # - +:fail_fast+ (default) — cancels all remaining tasks on the first error
+  # - +:collect_all+ — waits for every task to complete, then raises the first error
+  # - +:skip_failed+ — ignores failed tasks and returns only successful results
+  #
+  # {#cancel_all!} cancels every task in the group and joins them, guaranteeing
+  # that the active child task count reaches zero before returning.
+  #
+  # @example Parallel tool calls with a concurrency cap
+  #   group = Phronomy::TaskGroup.new(limit: 5)
+  #   tasks = items.map { |item| group.spawn { process(item) } }
+  #   results = group.await_all   # Array in spawn order
+  #
+  # @example Collect-all failure policy
+  #   group = Phronomy::TaskGroup.new(failure_policy: :collect_all)
+  #   …
+  class TaskGroup
+    # Valid failure policies.
+    FAILURE_POLICIES = %i[fail_fast collect_all skip_failed].freeze
+
+    # @param limit          [Integer, Float::INFINITY] maximum simultaneous active tasks
+    # @param failure_policy [Symbol] one of {FAILURE_POLICIES} (default +:fail_fast+)
+    # @param runtime        [Runtime, nil] runtime used to spawn tasks via {Runtime#spawn};
+    #   when +nil+, tasks are created directly via +Task.new+ (backward-compatible mode).
+    #   Pass +runtime: self+ from {Runtime#task_group} to keep task execution consistent
+    #   with the configured scheduler backend.
+    # @api private
+    def initialize(limit: Float::INFINITY, failure_policy: :fail_fast, runtime: nil)
+      raise ArgumentError, "unknown failure_policy: #{failure_policy}" unless FAILURE_POLICIES.include?(failure_policy)
+
+      @limit = limit
+      @failure_policy = failure_policy
+      @runtime = runtime
+      @tasks = []
+      @mutex = Mutex.new
+      @cond = ConditionVariable.new
+      @active = 0
+    end
+
+    # Spawns a new task within the group.
+    # Blocks if the number of currently active tasks equals +limit+.
+    #
+    # @yield block to execute concurrently
+    # @return [Task] the spawned task
+    # @api private
+    def spawn(&block)
+      wait_for_slot!
+
+      task = if @runtime
+        @runtime.spawn(name: "task-group-worker") do
+          block.call
+        ensure
+          release_slot!
+        end
+      else
+        Task.new do
+          block.call
+        ensure
+          release_slot!
+        end
+      end
+
+      @mutex.synchronize { @tasks << task }
+      task
+    end
+
+    # Waits for all spawned tasks to complete.
+    # Returns results in spawn order.
+    #
+    # Failure behaviour is controlled by the +failure_policy+ set at
+    # construction time:
+    # - +:fail_fast+    — raises the first error after cancelling unfinished tasks
+    # - +:collect_all+  — waits for all tasks, then raises the first error
+    # - +:skip_failed+  — returns only the values of successful tasks
+    #
+    # @return [Array] results in spawn order (or successful-only for :skip_failed)
+    # @raise [Exception] when any task failed (except :skip_failed)
+    # @api private
+    def await_all
+      tasks = @mutex.synchronize { @tasks.dup }
+      return [] if tasks.empty?
+
+      if Phronomy::Runtime::Scheduler.current
+        _await_all_cooperative(tasks)
+      else
+        _await_all_threaded(tasks)
+      end
+    end
+
+    private
+
+    # Cooperative await_all for DeterministicScheduler context.
+    # Uses on_complete callbacks + AsyncQueue to observe task completions in
+    # arrival order (not spawn order), matching the fail-fast semantics of the
+    # threaded path.  AsyncQueue#pop suspends the current Fiber cooperatively
+    # rather than blocking the OS thread.
+    # @api private
+    # @param tasks [Array<Task>]
+    # @return [Array]
+    def _await_all_cooperative(tasks)
+      completion_q = AsyncQueue.new
+      tasks.each_with_index do |task, idx|
+        task.on_complete do |value, error|
+          completion_q.push({index: idx, value: value, error: error})
+        end
+      end
+
+      entries = Array.new(tasks.length)
+      cancelled = false
+      fail_fast_error = nil
+
+      tasks.length.times do
+        entry = completion_q.pop  # cooperative suspend via scheduler signal
+        entries[entry[:index]] = entry
+
+        if entry[:error] && @failure_policy == :fail_fast && !cancelled
+          cancelled = true
+          fail_fast_error = entry[:error]
+          tasks.each { |t| t.cancel! unless t.done? }
+        end
+      end
+
+      case @failure_policy
+      when :fail_fast
+        raise fail_fast_error if fail_fast_error
+        entries.map { |r| r[:value] }
+      when :skip_failed
+        entries.filter_map { |r| r[:value] unless r[:error] }
+      else # :collect_all
+        errors = entries.filter_map { |r| r[:error] }
+        raise errors.first if errors.any?
+        entries.map { |r| r[:value] }
+      end
+    end
+
+    # Thread-blocking await_all for ThreadBackend / ImmediateBackend context.
+    # Uses Task#on_complete callbacks instead of spawning N additional watcher
+    # tasks (Issue #328).  on_complete receives the task's value and error
+    # directly — no await call is needed, eliminating the risk of a self-join
+    # when the callback fires inside the task's own execution thread.
+    def _await_all_threaded(tasks)
+      completion_q = Queue.new
+      tasks.each_with_index do |task, idx|
+        task.on_complete do |value, error|
+          completion_q.push({index: idx, value: value, error: error})
+        end
+      end
+
+      entries = Array.new(tasks.length)
+      cancelled = false
+      # The error that triggered fail_fast cancellation (tracked separately so
+      # we raise it rather than a secondary CancellationError from cancelled tasks).
+      fail_fast_error = nil
+
+      tasks.length.times do
+        entry = completion_q.pop
+        entries[entry[:index]] = entry
+
+        if entry[:error] && @failure_policy == :fail_fast && !cancelled
+          cancelled = true
+          fail_fast_error = entry[:error]
+          tasks.each { |t| t.cancel! unless t.done? }
+        end
+      end
+
+      case @failure_policy
+      when :fail_fast
+        raise fail_fast_error if fail_fast_error
+        entries.map { |r| r[:value] }
+      when :skip_failed
+        entries.filter_map { |r| r[:value] unless r[:error] }
+      else # :collect_all
+        errors = entries.filter_map { |r| r[:error] }
+        raise errors.first if errors.any?
+        entries.map { |r| r[:value] }
+      end
+    end
+
+    public
+
+    # Cancels all tasks currently in the group and waits for each to finish.
+    # After this method returns, the active child task count is guaranteed to
+    # be zero.
+    #
+    # Note: if a task is cancelled before its block has started executing, the
+    # internal +ensure+ clause inside the block may not run, so @active is
+    # reset explicitly after all tasks are joined.
+    #
+    # @return [self]
+    # @api private
+    def cancel_all!
+      tasks = @mutex.synchronize { @tasks.dup }
+      tasks.each(&:cancel!)
+      tasks.each do |t|
+        t.join
+      rescue
+        nil
+      end
+      # Force @active to zero: tasks cancelled before block execution starts
+      # may not decrement @active via their ensure clause.
+      scheduler = Phronomy::Runtime::Scheduler.current
+      if scheduler && @coop_signal
+        @active = 0
+        scheduler.raise_signal_all(@coop_signal)
+      else
+        @mutex.synchronize do
+          @active = 0
+          @cond.broadcast
+        end
+      end
+      self
+    end
+
+    # Returns the number of currently executing child tasks.
+    # @return [Integer]
+    # @api private
+    def active_task_count
+      @mutex.synchronize { @active }
+    end
+
+    private
+
+    def wait_for_slot!
+      scheduler = Phronomy::Runtime::Scheduler.current
+      if scheduler
+        @coop_signal ||= scheduler.new_signal
+        loop do
+          if @active < @limit
+            @active += 1
+            return
+          end
+          scheduler.wait_for_signal(@coop_signal)
+        end
+      else
+        @mutex.synchronize do
+          @cond.wait(@mutex) while @active >= @limit
+          @active += 1
+        end
+      end
+    end
+
+    def release_slot!
+      scheduler = Phronomy::Runtime::Scheduler.current
+      if scheduler && @coop_signal
+        @active -= 1
+        scheduler.raise_signal(@coop_signal)
+      else
+        @mutex.synchronize do
+          @active -= 1
+          @cond.signal
+        end
+      end
+    end
+  end
+end

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

@@ -97,6 +97,37 @@ module Phronomy
           @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::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
+        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]
@@ -145,6 +176,33 @@ module Phronomy
           @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
+        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
@@ -248,7 +306,7 @@ module Phronomy
       # @param cancellation_token [Phronomy::CancellationToken, nil] optional; takes precedence over the thread-local token
       # @api public
       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 +319,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,6 +340,24 @@ 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::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::CancellationToken, nil]
+      # @return [#await]
+      # @api public
+      def call_async(args, cancellation_token: nil)
+        Phronomy::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
@@ -322,6 +399,37 @@ module Phronomy
         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