phronomy 0.26.0 → 0.28.0

data/lib/phronomy/agent/tool_invocation_session_builder.rb

@@ -1,276 +0,0 @@
-# frozen_string_literal: true
-
-require "state_machines"
-
-module Phronomy
-  module Agent
-    # Builds an FSMSession for one ToolInvocation.
-    # Async completion is represented only by explicit FSM events.
-    class ToolInvocationSessionBuilder
-      AUTO_STATE_SET = {idle: true, validating: true, queued: true}.freeze
-
-      DECLARED_STATES = %i[
-        idle validating authorizing awaiting_approval authorized queued running
-        completed failed rejected cancelled
-      ].freeze
-
-      WAIT_STATES = %i[awaiting_approval authorized].freeze
-
-      EXTERNAL_EVENTS = {
-        authorization_completed: [
-          {from: :authorizing, to: :cancelled, guard: ->(ctx) { ctx.cancelled? }},
-          {from: :authorizing, to: :failed, guard: ->(ctx) { ctx.failed? }},
-          {from: :authorizing, to: :rejected, guard: ->(ctx) { ctx.rejected? }},
-          {from: :authorizing, to: :awaiting_approval, guard: ->(ctx) { ctx.awaiting_approval? }},
-          {from: :authorizing, to: :authorized, guard: ->(ctx) { ctx.authorized? }}
-        ],
-        execution_completed: [
-          {from: :running, to: :cancelled, guard: ->(ctx) { ctx.cancelled? }},
-          {from: :running, to: :failed, guard: ->(ctx) { ctx.failed? }},
-          {from: :running, to: :completed, guard: ->(ctx) { ctx.execution_completed? }}
-        ],
-        approve: [{from: :awaiting_approval, to: :authorized, guard: nil}],
-        reject: [{from: :awaiting_approval, to: :rejected, guard: nil}],
-        dispatch: [{from: :authorized, to: :queued, guard: nil}],
-        cancel: [
-          {from: :awaiting_approval, to: :cancelled, guard: nil},
-          {from: :authorized, to: :cancelled, guard: nil},
-          {from: :queued, to: :cancelled, guard: nil},
-          {from: :running, to: :cancelled, guard: nil}
-        ]
-      }.freeze
-
-      def self.build(
-        tool_invocation:,
-        parent_event_sink:,
-        runtime: Phronomy::Runtime.instance
-      )
-        build_session(
-          tool_invocation: tool_invocation,
-          parent_event_sink: parent_event_sink,
-          runtime: runtime
-        )
-      end
-
-      def self.build_for_resume(
-        tool_invocation:,
-        parent_event_sink:,
-        resume_event:,
-        resume_phase:,
-        runtime: Phronomy::Runtime.instance
-      )
-        build_session(
-          tool_invocation: tool_invocation,
-          parent_event_sink: parent_event_sink,
-          runtime: runtime,
-          resume_event: resume_event,
-          resume_phase: resume_phase
-        )
-      end
-
-      def self.build_session(
-        tool_invocation:,
-        parent_event_sink:,
-        runtime:,
-        resume_event: nil,
-        resume_phase: nil
-      )
-        event_sink = Phronomy::FSMSession::EventSink.new(event_loop: runtime.event_loop)
-        actions = build_entry_actions(runtime, event_sink, parent_event_sink)
-        phase_machine = build_phase_machine(actions)
-
-        Phronomy::FSMSession.new(
-          context: tool_invocation,
-          event_sink: event_sink,
-          entry_point: :idle,
-          phase_machine_class: phase_machine,
-          entry_actions: {},
-          auto_state_set: AUTO_STATE_SET,
-          declared_states: DECLARED_STATES,
-          wait_state_names: WAIT_STATES,
-          external_events: EXTERNAL_EVENTS,
-          recursion_limit: 20,
-          event_loop: runtime.event_loop,
-          resume_event: resume_event,
-          resume_phase: resume_phase
-        )
-      end
-      private_class_method :build_session
-
-      def self.build_entry_actions(runtime, event_sink, parent_event_sink)
-        {
-          validating: [method(:validating_action)],
-          authorizing: [method(:authorizing_action).curry.call(runtime, event_sink)],
-          awaiting_approval: [method(:awaiting_approval_action).curry.call(parent_event_sink)],
-          authorized: [method(:authorized_action).curry.call(parent_event_sink)],
-          queued: [method(:queued_action)],
-          running: [method(:running_action).curry.call(runtime, event_sink)],
-          completed: [method(:completed_action).curry.call(parent_event_sink)],
-          failed: [method(:failed_action).curry.call(parent_event_sink)],
-          rejected: [method(:rejected_action).curry.call(parent_event_sink)],
-          cancelled: [method(:cancelled_action).curry.call(parent_event_sink)]
-        }
-      end
-      private_class_method :build_entry_actions
-
-      def self.build_phase_machine(entry_actions)
-        callbacks = entry_actions
-        callback_builder = method(:build_entry_callback)
-
-        Class.new do
-          attr_accessor :context, :current_event
-
-          state_machine :phase, initial: :idle do
-            state :idle
-            state :validating
-            state :authorizing
-            state :awaiting_approval
-            state :authorized
-            state :queued
-            state :running
-            state :completed
-            state :failed
-            state :rejected
-            state :cancelled
-
-            event :state_completed do
-              transition idle: :validating
-              transition validating: :failed, if: ->(m) { m.context&.failed? }
-              transition validating: :completed, if: ->(m) { m.context&.validation_completed? }
-              transition validating: :authorizing, if: ->(m) { m.context&.validation_passed? }
-              transition queued: :running
-            end
-
-            event :authorization_completed do
-              transition authorizing: :cancelled, if: ->(m) { m.context&.cancelled? }
-              transition authorizing: :failed, if: ->(m) { m.context&.failed? }
-              transition authorizing: :rejected, if: ->(m) { m.context&.rejected? }
-              transition authorizing: :awaiting_approval, if: ->(m) { m.context&.awaiting_approval? }
-              transition authorizing: :authorized, if: ->(m) { m.context&.authorized? }
-            end
-
-            event :execution_completed do
-              transition running: :cancelled, if: ->(m) { m.context&.cancelled? }
-              transition running: :failed, if: ->(m) { m.context&.failed? }
-              transition running: :completed, if: ->(m) { m.context&.execution_completed? }
-            end
-
-            event(:approve) { transition awaiting_approval: :authorized }
-            event(:reject) { transition awaiting_approval: :rejected }
-            event(:dispatch) { transition authorized: :queued }
-            event :cancel do
-              transition awaiting_approval: :cancelled
-              transition authorized: :cancelled
-              transition queued: :cancelled
-              transition running: :cancelled
-            end
-
-            callbacks.each do |state_name, callables|
-              callables.each do |callable|
-                after_transition(
-                  to: state_name,
-                  do: callback_builder.call(callable, state_name)
-                )
-              end
-            end
-          end
-        end
-      end
-      private_class_method :build_phase_machine
-
-      def self.build_entry_callback(callable, state_name)
-        ->(machine) {
-          result = callable.call(machine.context)
-          if result.is_a?(Phronomy::TaskResult)
-            raise Phronomy::InvalidAsyncEntryActionError,
-              "Tool entry action for #{state_name.inspect} returned Phronomy::TaskResult"
-          end
-          machine.context = result if result.respond_to?(:set_graph_metadata)
-        }
-      end
-      private_class_method :build_entry_callback
-
-      def self.validating_action(invocation)
-        invocation.validate!
-      end
-      private_class_method :validating_action
-
-      def self.authorizing_action(runtime, event_sink, invocation)
-        invocation.start_authorization(runtime: runtime) do |outcome|
-          post_to_session(event_sink, :authorization_completed, outcome)
-        end
-        invocation
-      end
-      private_class_method :authorizing_action
-
-      def self.awaiting_approval_action(parent_event_sink, invocation)
-        invocation.mark_awaiting_approval!
-        notify_parent(parent_event_sink, invocation, :tool_approval_required)
-        invocation
-      end
-      private_class_method :awaiting_approval_action
-
-      def self.authorized_action(parent_event_sink, invocation)
-        invocation.mark_authorized!
-        notify_parent(parent_event_sink, invocation, :tool_authorized)
-        invocation
-      end
-      private_class_method :authorized_action
-
-      def self.queued_action(invocation)
-        invocation.mark_queued!
-      end
-      private_class_method :queued_action
-
-      def self.running_action(runtime, event_sink, invocation)
-        invocation.start_execution(runtime: runtime) do |outcome|
-          post_to_session(event_sink, :execution_completed, outcome)
-        end
-        invocation.mark_running!
-        invocation
-      end
-      private_class_method :running_action
-
-      def self.completed_action(parent_event_sink, invocation)
-        notify_parent(parent_event_sink, invocation, :tool_completed)
-        invocation
-      end
-      private_class_method :completed_action
-
-      def self.failed_action(parent_event_sink, invocation)
-        notify_parent(parent_event_sink, invocation, :tool_failed)
-        invocation
-      end
-      private_class_method :failed_action
-
-      def self.rejected_action(parent_event_sink, invocation)
-        invocation.mark_rejected!
-        notify_parent(parent_event_sink, invocation, :tool_rejected)
-        invocation
-      end
-      private_class_method :rejected_action
-
-      def self.cancelled_action(parent_event_sink, invocation)
-        invocation.mark_cancelled!
-        notify_parent(parent_event_sink, invocation, :tool_cancelled)
-        invocation
-      end
-      private_class_method :cancelled_action
-
-      def self.post_to_session(event_sink, event_type, payload)
-        return if event_sink.post(event_type, payload)
-
-        Phronomy.configuration.logger&.warn(
-          "[Phronomy] Dropped #{event_type.inspect} for " \
-          "FSMSession #{event_sink.fsm_session_id}"
-        )
-      end
-      private_class_method :post_to_session
-
-      def self.notify_parent(parent_event_sink, invocation, event_type)
-        parent_event_sink.post(event_type, {tool_invocation_id: invocation.id})
-      end
-      private_class_method :notify_parent
-    end
-  end
-end

data/lib/phronomy/configuration.rb

@@ -1,59 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  # Holds global configuration for the entire framework.
-  class Configuration
-    STREAM_CALLBACK_ERROR_POLICIES = %i[report fail_task].freeze
-    private_constant :STREAM_CALLBACK_ERROR_POLICIES
-
-    attr_accessor :default_model
-    attr_accessor :default_embedding_model
-    attr_accessor :tracer
-    attr_accessor :before_llm_input
-    attr_accessor :default_output_reserve
-    attr_accessor :recursion_limit
-    attr_accessor :parallel_tool_execution
-    attr_accessor :trace_pii
-    attr_accessor :logger
-    attr_accessor :event_loop_stop_grace_seconds
-    attr_accessor :persistence
-    attr_accessor :tool_result_max_size
-    attr_accessor :llm_adapter
-    attr_accessor :event_loop_starvation_threshold_seconds
-    attr_accessor :event_loop_dispatch_threshold_seconds
-    attr_reader :stream_callback_error_policy
-    attr_accessor :offload_pool_size
-    attr_accessor :offload_queue_size
-    attr_accessor :authorization_pool_size
-    attr_accessor :authorization_queue_size
-    attr_accessor :authorization_timeout
-
-    def stream_callback_error_policy=(value)
-      unless STREAM_CALLBACK_ERROR_POLICIES.include?(value)
-        allowed = STREAM_CALLBACK_ERROR_POLICIES.map(&:inspect).join(", ")
-        raise Phronomy::ConfigurationError,
-          "stream_callback_error_policy must be one of: #{allowed}"
-      end
-
-      @stream_callback_error_policy = value
-    end
-
-    def initialize
-      @recursion_limit = 25
-      @tracer = Phronomy::Tracing::NullTracer.new
-      @trace_pii = false
-      @parallel_tool_execution = false
-      @event_loop_stop_grace_seconds = 5
-      @llm_adapter = Phronomy::LLMAdapter::RubyLLM.new
-      @event_loop_starvation_threshold_seconds = nil
-      @event_loop_dispatch_threshold_seconds = nil
-      @stream_callback_error_policy = :report
-      @offload_pool_size = 10
-      @offload_queue_size = 100
-      @authorization_pool_size = 4
-      @authorization_queue_size = 100
-      @authorization_timeout = 5
-      @persistence = nil
-    end
-  end
-end

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

@@ -1,124 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Concurrency
-    # Represents a bounded execution scope that owns a {CancellationToken} and
-    # optionally a {Deadline}.
-    #
-    # +CancellationScope+ replaces ad-hoc +Timeout.timeout+ calls in agent and
-    # tool code. All work performed within a scope should observe the scope's
-    # token; when the scope is cancelled (explicitly or by deadline expiry) the
-    # token is cancelled and all child tasks that check it will stop.
-    #
-    # @example Time-bounded invocation
-    #   scope = Phronomy::Concurrency::CancellationScope.new.deadline_in(30)
-    #   result = scope.pop_queue(completion_queue) do
-    #     raise Phronomy::TimeoutError, "timed out"
-    #   end
-    #
-    # @example Explicit cancellation
-    #   scope = Phronomy::Concurrency::CancellationScope.new
-    #   operation = Phronomy::Runtime.instance.offload.submit(
-    #     cancellation_token: scope.token
-    #   ) { synchronous_operation }
-    #   scope.cancel! if some_condition
-    class CancellationScope
-      # @return [CancellationToken] the token owned by this scope
-      attr_reader :token
-
-      # @return [Deadline, nil] the deadline attached to this scope, if any
-      attr_reader :deadline
-
-      # @param parent_token [CancellationToken, nil] when provided, cancellation of
-      #   the parent token is propagated to this scope's token via a callback
-      #   (for explicit cancel) and/or the Runtime timer queue (for monotonic
-      #   deadline expiry). No polling thread is spawned.
-      # @api private
-      def initialize(parent_token: nil)
-        @token = Phronomy::Concurrency::CancellationToken.new
-        @deadline = nil
-
-        if parent_token
-          # Propagate explicit cancel() from parent to child via callback.
-          parent_token.on_cancel { @token.cancel! }
-
-          # Propagate monotonic-deadline expiry from parent to child via the
-          # timer queue (avoids a polling thread).
-          remaining = parent_token.remaining_monotonic_seconds
-          if !remaining.nil?
-            if remaining <= 0
-              @token.cancel!
-            else
-              Phronomy::Runtime.instance.timer_queue.schedule(seconds: remaining) do
-                @token.cancel!
-              end
-            end
-          end
-        end
-      end
-
-      # Attaches a deadline that will cancel this scope after +seconds+.
-      #
-      # @param seconds [Numeric] timeout duration
-      # @return [self]
-      # @api private
-      def deadline_in(seconds)
-        @deadline = Phronomy::Concurrency::Deadline.in(seconds)
-        @deadline.attach_to(@token)
-        self
-      end
-
-      # Cancels this scope immediately.
-      # @return [void]
-      # @api private
-      def cancel!
-        @token.cancel!
-      end
-
-      # Returns +true+ if this scope has been cancelled.
-      # @return [Boolean]
-      # @api private
-      def cancelled?
-        @token.cancelled?
-      end
-
-      # Returns the remaining time in seconds before the deadline expires,
-      # or +nil+ when no deadline is set.
-      # @return [Float, nil]
-      # @api private
-      def remaining_seconds
-        @deadline&.remaining_seconds
-      end
-
-      # Pops from +queue+ with a timeout derived from the attached deadline (or
-      # +fallback_timeout+ seconds when no deadline is set). If the pop times out,
-      # the scope is cancelled and the block is called (or a {TimeoutError} raised).
-      #
-      # @param queue [Phronomy::Concurrency::AsyncQueue] the queue to pop from
-      # @param fallback_timeout [Numeric, nil] used when no deadline is attached
-      # @yield called when the operation times out
-      # @raise [Phronomy::TimeoutError] when no block is given and a timeout occurs
-      # @return [Object] the popped value
-      # @api private
-      def pop_queue(queue, fallback_timeout: nil)
-        timeout = @deadline&.remaining_seconds || fallback_timeout
-        result = if timeout
-          queue.pop(timeout: timeout)
-        else
-          queue.pop
-        end
-
-        if result.nil?
-          cancel!
-          if block_given?
-            yield
-          else
-            raise Phronomy::TimeoutError, "CancellationScope timed out"
-          end
-        end
-
-        result
-      end
-    end
-  end
-end

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

@@ -1,43 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Concurrency
-    # Connects explicit invocation controls before operation admission. Its token
-    # is private: cancelling it never cancels the application's shared tokens.
-    # Used by Execution's Agent and Blocking adapters; it owns no worker.
-    # @api private
-    class OperationBinding
-      attr_reader :token, :scope
-
-      def initialize(invocation_context:, cancellation_token:)
-        if !invocation_context.nil? && !invocation_context.is_a?(InvocationContext)
-          raise TypeError, "invocation_context must be a Phronomy::InvocationContext or nil"
-        end
-        @scope = invocation_context&.__execution_scope
-        @token = CancellationToken.new
-        @subscriptions = Subscriptions.new
-        [invocation_context&.cancellation_token, cancellation_token].compact.uniq.each do |source|
-          @subscriptions.cancellation(source) { @token.cancel! }
-        end
-        if !@scope && invocation_context&.deadline
-          @subscriptions.after(invocation_context.deadline.remaining_seconds) { @token.cancel! }
-        end
-        @token.cancel! if @scope && !@scope.__open?
-      end
-
-      def bind(result)
-        result.__bind_execution(@scope)
-        track(result)
-      end
-
-      def track(result)
-        @subscriptions.result(result) { @subscriptions.close }
-        result
-      end
-
-      def close
-        @subscriptions.close
-      end
-    end
-  end
-end