phronomy 0.16.0 → 0.18.0

data/lib/phronomy/llm_context_window/token_budget.rb

@@ -2,96 +2,25 @@
 
 module Phronomy
   module LlmContextWindow
-    # Raised when a model name is not found in the RubyLLM model registry and
-    # no explicit context_window was provided.
-    class UnknownModelError < Phronomy::Error; end
-
-    # Calculates the effective token budget available for conversation history
-    # and injected knowledge within a single LLM request.
-    #
-    # The window is divided as follows:
-    #
-    #   context_window (total)
-    #   ├─ max_output_tokens  (reserved for model output = max_output_tokens)
-    #   ├─ overhead           (reserved for system prompt + tool definitions)
-    #   └─ effective_input_limit  (available for memory + knowledge)
-    #
-    # @example Auto-derive from RubyLLM model registry
-    #   budget = Phronomy::LlmContextWindow::TokenBudget.new(model: "claude-3-5-sonnet-20241022")
-    #
-    # @example Explicit values (useful for local / unknown models)
-    #   budget = Phronomy::LlmContextWindow::TokenBudget.new(
-    #     context_window:    32_768,
-    #     max_output_tokens: 4_096
-    #   )
-    #
-    # @example With overhead for instructions + tool definitions
-    #   budget = Phronomy::LlmContextWindow::TokenBudget.new(
-    #     model:    "gpt-4o",
-    #     overhead: 800
-    #   )
+    # Immutable arithmetic value for one resolved model context budget.
+    # Model-registry lookup belongs to Agent::TokenBudgetResolver.
     class TokenBudget
-      # @return [Integer] total token limit of the model
-      attr_reader :context_window
-
-      # @return [Integer] tokens reserved for model output
-      attr_reader :max_output_tokens
+      attr_reader :context_window, :max_output_tokens
 
-      # @return [Integer] tokens reserved for instructions and tool definitions
-      attr_reader :overhead
-
-      # @param model             [String, nil]  model identifier looked up in RubyLLM
-      # @param context_window    [Integer, nil] explicit total token limit
-      # @param max_output_tokens [Integer, nil] explicit output reservation; when nil
-      #                                         and model is given, uses max_output_tokens
-      # @param overhead          [Integer]      tokens reserved for instructions/tools
       # @api private
-      # mutant:disable - multiple genuine equivalent mutations: overhead/context_window/max_output_tokens .to_i vs .to_int vs Integer() vs omitted are equivalent for Integer inputs; (max_output_tokens||0).to_i vs (max_output_tokens).to_i and (||nil).to_i are genuine because nil.to_i==0; overhead:nil default is genuine because nil.to_i==0
-      def initialize(model: nil, context_window: nil, max_output_tokens: nil, overhead: 0)
-        @overhead = overhead.to_i
-
-        if context_window
-          # Explicit values — no registry lookup needed.
-          @context_window = context_window.to_i
-          @max_output_tokens = (max_output_tokens || 0).to_i
-        elsif model
-          ruby_llm_model = lookup_model!(model)
-          @context_window = ruby_llm_model.context_window.to_i
-          @max_output_tokens = (max_output_tokens || ruby_llm_model.max_output_tokens).to_i
-        else
-          raise ArgumentError, "Provide either model: or context_window:"
-        end
+      def initialize(context_window:, max_output_tokens:)
+        @context_window = Integer(context_window)
+        @max_output_tokens = Integer(max_output_tokens)
       end
 
-      # Tokens available for conversation history and knowledge after reservations.
-      # Always >= 0.
-      #
-      # @return [Integer]
       # @api private
       def effective_input_limit
-        [@context_window - @max_output_tokens - @overhead, 0].max
+        [@context_window - @max_output_tokens, 0].max
       end
 
-      # Tokens still available after `used` tokens have been allocated.
-      #
-      # @param used [Integer] tokens already committed (e.g. from knowledge injection)
-      # @return [Integer] remaining tokens (always >= 0)
       # @api private
-      # mutant:disable - used.to_i vs used vs used.to_int vs Integer(used) are genuine equivalents when used is an Integer; used:nil default is genuine because nil.to_i==0==default 0
       def available(used: 0)
-        [effective_input_limit - used.to_i, 0].max
-      end
-
-      private
-
-      # mutant:disable - raise(UnknownModelError) and raise(UnknownModelError,nil) and raise(UnknownModelError,"Model '#{nil}' not found") in both branches are genuine equivalents (spec checks exception class only, not message text)
-      def lookup_model!(model_name)
-        found = RubyLLM.models.find(model_name)
-        raise UnknownModelError, "Model '#{model_name}' not found in RubyLLM registry" unless found
-
-        found
-      rescue RubyLLM::ModelNotFoundError
-        raise UnknownModelError, "Model '#{model_name}' not found in RubyLLM registry"
+        [effective_input_limit - Integer(used), 0].max
       end
     end
   end

data/lib/phronomy/metrics.rb

@@ -1,41 +1,26 @@
 # frozen_string_literal: true
 
 module Phronomy
-  # Task-centric observability snapshot (Issue #276, extended in #307).
-  #
-  # Collects live metrics from the shared Runtime components
-  # (BlockingAdapterPool, EventLoop, and Runtime task registry) and returns
-  # them as a plain Hash so they can be forwarded to any monitoring backend
-  # (Prometheus, OpenTelemetry, StatsD, etc.).
-  #
-  # All metrics are read at the moment {.snapshot} is called; no
-  # persistent state is held here.
-  #
-  # @example Exporting to a metrics endpoint
-  #   data = Phronomy::Metrics.snapshot
-  #   # => { blocking_pool_active: 2, active_agent_tasks: 1, ... }
+  # Runtime observability snapshot for the two concurrency boundaries:
+  # EventLoop and OffloadPool.
   module Metrics
-    # Returns a Hash of current observability metrics.
-    #
-    # @return [Hash{Symbol => Numeric}]
-    # @api public
     def self.snapshot
       runtime = Runtime.instance
-      pool = runtime.blocking_io
-      el = runtime.event_loop
-      task_snap = runtime.task_snapshot
+      pool = runtime.offload
+      event_loop = runtime.event_loop
 
       {
-        blocking_pool_active: pool.active_count,
-        blocking_pool_queue_length: pool.queue_depth,
-        blocking_pool_abandoned_total: pool.abandoned_count,
-        blocking_pool_size: pool.pool_size,
-        event_loop_queue_depth: el.queue_depth,
-        event_loop_queue_max_depth: el.max_queue_depth,
-        event_loop_lag_last_ms: (el.last_lag_seconds * 1000).round(3),
-        event_loop_lag_max_ms: (el.max_lag_seconds * 1000).round(3),
-        event_loop_lag_average_ms: (el.average_lag_seconds * 1000).round(3)
-      }.merge(task_snap)
+        offload_pool_active: pool.active_count,
+        offload_pool_queue_length: pool.queue_depth,
+        offload_pool_abandoned_active: pool.abandoned_active_count,
+        offload_pool_abandoned_total: pool.abandoned_count,
+        offload_pool_size: pool.pool_size,
+        event_loop_queue_depth: event_loop.queue_depth,
+        event_loop_queue_max_depth: event_loop.max_queue_depth,
+        event_loop_lag_last_ms: (event_loop.last_lag_seconds * 1000).round(3),
+        event_loop_lag_max_ms: (event_loop.max_lag_seconds * 1000).round(3),
+        event_loop_lag_average_ms: (event_loop.average_lag_seconds * 1000).round(3)
+      }
     end
   end
 end

data/lib/phronomy/multi_agent/fan_out_invocation.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Phronomy
+  module MultiAgent
+    # Mutable FSM context for one fan-out operation.
+    class FanOutInvocation
+      Child = Data.define(:index, :agent, :input, :config, :thread_id)
+
+      attr_reader :id, :phase, :results
+
+      def initialize(children:, max_concurrency:, on_error:)
+        @id = SecureRandom.uuid.to_s
+        @phase = nil
+        @children = children
+        @max_concurrency = max_concurrency || children.length
+        @on_error = on_error
+        @pending = children.dup
+        @active = {}
+        @results = Array.new(children.length)
+        @child_errors = Array.new(children.length)  # indexed by input order
+        @fatal_error = nil   # driver_failed / timeout / cancel
+        @cancelled = false
+        @timed_out = false
+        @session_id = nil
+      end
+
+      def set_graph_metadata(thread_id: nil, phase: nil)
+        @session_id = thread_id if thread_id
+        @phase = phase
+      end
+
+      def handle_fsm_event(event)
+        case event.type
+        when :child_completed
+          payload = event.payload
+          index = payload.fetch(:index)
+          @active.delete(index)
+          child_error = payload[:error]
+          if child_error
+            if @on_error == :raise
+              @child_errors[index] = child_error
+              # Signal cancellation so other children can stop early, but continue
+              # waiting for all active children to respond so we can return the
+              # first error in INPUT ORDER (not arrival order).
+              cancel_active_children! unless @child_errors.any?(&:itself)
+            end
+          else
+            @results[index] = payload[:result]
+          end
+          true
+        when :driver_failed
+          @fatal_error ||= event.payload.fetch(:error)
+          cancel_active_children!
+          true
+        when :timeout
+          @timed_out = true
+          @fatal_error ||= Phronomy::TimeoutError.new(event.payload.fetch(:message))
+          cancel_active_children!
+          true
+        when :cancel
+          @cancelled = true
+          @fatal_error ||= Phronomy::CancellationError.new("fan-out cancelled")
+          cancel_active_children!
+          true
+        else
+          false
+        end
+      end
+
+      def start_available!(runtime)
+        return self if @fatal_error
+
+        while @active.length < @max_concurrency && (child = @pending.shift)
+          child_config = build_child_config(child.config)
+          handle = child.agent.invoke_async(
+            child.input,
+            config: child_config,
+            thread_id: child.thread_id
+          )
+          @active[child.index] = {handle: handle, token: child_config[:cancellation_token]}
+          # [child.index].each creates a block parameter with a unique binding
+          # per iteration, avoiding the while-loop variable capture problem.
+          [child.index].each do |captured_index|
+            handle.on_complete do |result, error|
+              runtime.event_loop.post_to_session(
+                Phronomy::Event.new(
+                  type: :child_completed,
+                  target_id: @id,
+                  payload: {index: captured_index, result: result, error: error}
+                )
+              )
+            end
+          end
+        end
+        self
+      rescue => caught
+        @fatal_error ||= caught
+        cancel_active_children!
+        runtime.event_loop.post_to_session(
+          Phronomy::Event.new(
+            type: :driver_failed,
+            target_id: @id,
+            payload: {error: caught}
+          )
+        )
+        self
+      end
+
+      def completed?
+        !failed? && @pending.empty? && @active.empty?
+      end
+
+      def failed?
+        return true if @fatal_error
+        @on_error == :raise && @pending.empty? && @active.empty? && @child_errors.any?(&:itself)
+      end
+
+      def error
+        @fatal_error || @child_errors.find(&:itself)
+      end
+
+      def timed_out?
+        @timed_out
+      end
+
+      def cancelled?
+        @cancelled
+      end
+
+      private
+
+      def build_child_config(config)
+        config.dup
+      end
+
+      def cancel_active_children!
+        @pending.clear
+        @active.each_value do |entry|
+          entry[:token]&.cancel!
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/multi_agent/fan_out_session_builder.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require "state_machines"
+
+module Phronomy
+  module MultiAgent
+    # Builds and registers a fan-out coordination FSMSession.
+    class FanOutSessionBuilder
+      AUTO_STATE_SET = {idle: true}.freeze
+      DECLARED_STATES = %i[idle running completed failed timed_out cancelled].freeze
+      WAIT_STATES = [].freeze
+
+      def self.start(
+        invocation:,
+        timeout: nil,
+        cancellation_token: nil,
+        runtime: Phronomy::Runtime.instance
+      )
+        result = Phronomy::Task.deferred(name: "fan-out:#{invocation.id}")
+
+        if cancellation_token&.cancelled?
+          result.fail(Phronomy::CancellationError.new("fan-out cancelled"))
+          return result
+        end
+
+        source = Phronomy::Task.deferred(name: "fan-out-source:#{invocation.id}")
+        source.on_complete do |context, error|
+          if error
+            result.fail(error)
+          elsif context.error
+            result.fail(context.error)
+          else
+            result.complete(context.results)
+          end
+        end
+
+        session = build(invocation: invocation, runtime: runtime)
+        runtime.event_loop.register(session, completion: source)
+
+        if timeout
+          runtime.timer_queue.schedule(seconds: timeout) do
+            runtime.event_loop.post_to_session(
+              Phronomy::Event.new(
+                type: :timeout,
+                target_id: invocation.id,
+                payload: {message: "dispatch_parallel timed out after #{timeout}s"}
+              )
+            )
+          end
+        end
+
+        cancellation_token&.on_cancel do
+          runtime.event_loop.post_to_session(
+            Phronomy::Event.new(type: :cancel, target_id: invocation.id, payload: nil)
+          )
+        end
+
+        result
+      rescue => error
+        result ||= Phronomy::Task.deferred(name: "fan-out:registration")
+        result.fail(error)
+        result
+      end
+
+      def self.build(invocation:, runtime:)
+        phase_machine = build_phase_machine(runtime)
+        external_events = {
+          child_completed: [{from: :running, to: :running, guard: nil}],
+          driver_failed: [{from: :running, to: :failed, guard: nil}],
+          timeout: [{from: :running, to: :timed_out, guard: nil}],
+          cancel: [{from: :running, to: :cancelled, guard: nil}]
+        }
+
+        Phronomy::FSMSession.new(
+          id: invocation.id,
+          context: invocation,
+          entry_point: :idle,
+          entry_actions: {},
+          auto_state_set: AUTO_STATE_SET,
+          declared_states: DECLARED_STATES,
+          wait_state_names: WAIT_STATES,
+          external_events: external_events,
+          phase_machine_class: phase_machine,
+          recursion_limit: 10_000,
+          event_loop: runtime.event_loop
+        )
+      end
+      private_class_method :build
+
+      def self.build_phase_machine(runtime)
+        Class.new do
+          attr_accessor :context, :current_event
+
+          state_machine :phase, initial: :idle do
+            state :idle
+            state :running
+            state :completed
+            state :failed
+            state :timed_out
+            state :cancelled
+
+            event :state_completed do
+              transition idle: :running
+            end
+
+            event :child_completed do
+              transition running: :failed, if: ->(m) { m.context&.failed? }
+              transition running: :completed, if: ->(m) { m.context&.completed? }
+              transition running: :running
+            end
+
+            event(:driver_failed) { transition running: :failed }
+            event(:timeout) { transition running: :timed_out }
+            event(:cancel) { transition running: :cancelled }
+
+            after_transition to: :running do |machine|
+              machine.context.start_available!(runtime)
+            end
+          end
+        end
+      end
+      private_class_method :build_phase_machine
+    end
+  end
+end

data/lib/phronomy/multi_agent/handoff.rb

@@ -42,6 +42,7 @@ module Phronomy
         Class.new(Phronomy::Agent::Context::Capability::Base) do
           tool_name tn
           description desc
+          execution_mode :cooperative
           define_method(:execute) { sentinel_value }
         end
       end