phronomy 0.27.0 → 0.29.0

data/lib/phronomy/agent/persistence/handoff_state_repository.rb

@@ -1,58 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Agent
-    module Persistence
-      # Owns Handoff state encoding and the initial revision.
-      # @api private
-      class HandoffStateRepository
-        def initialize(view) = @view = view
-
-        def load(main_agent_id)
-          @view.atomic do |bound|
-            entry = bound.records(StorageSchema::HANDOFF_STATES).read(main_agent_id.to_s)
-            entry && decode(entry, main_agent_id)
-          end
-        end
-
-        def save(main_agent_id, expected_revision:, state:)
-          expected = expected_revision.nil? ? nil : Integer(expected_revision)
-          revision = expected.nil? ? 1 : expected + 1
-          unless state.main_agent_id == main_agent_id.to_s && state.handoff_revision == revision
-            raise Phronomy::Storage::SerializationError, "Handoff identity/revision mismatch"
-          end
-          record = Codec.encode_handoff_state(state)
-          @view.atomic do |bound|
-            records = bound.records(StorageSchema::HANDOFF_STATES)
-            values = {key: main_agent_id.to_s, attributes: {active_agent_id: state.active_agent_id}, record: record}
-            entry = if expected.nil?
-              records.insert(**values, revision: revision)
-            else
-              records.replace(**values, expected_revision: expected, next_revision: revision)
-            end
-            decode(entry, main_agent_id, revision: revision)
-          end
-        rescue Phronomy::Storage::NotFoundError => error
-          raise Phronomy::Storage::ConflictError, error.message
-        end
-
-        def delete(main_agent_id, expected_revision:)
-          @view.records(StorageSchema::HANDOFF_STATES).delete(key: main_agent_id.to_s, expected_revision: Integer(expected_revision))
-        end
-
-        private
-
-        def decode(entry, main_agent_id, revision: nil)
-          state = Codec.decode_handoff_state(entry.record)
-          valid = entry.key == main_agent_id.to_s && state.main_agent_id == entry.key &&
-            state.handoff_revision == entry.revision && (!revision || revision == entry.revision) &&
-            entry.attributes == {active_agent_id: state.active_agent_id}
-          unless valid
-            raise Phronomy::Storage::SerializationError, "backend returned another Handoff identity/revision"
-          end
-          state
-        end
-      end
-    end
-  end
-end

data/lib/phronomy/agent/persistence/queries.rb

@@ -1,61 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Agent
-    module Persistence
-      # Read and assemble domain results; the public entry point owns the execution-thread guard.
-      # @api private
-      class Queries
-        def initialize(repositories)
-          @repositories = repositories
-        end
-
-        def execution_result(execution_id)
-          execution = @repositories.executions.load(execution_id)
-          {
-            execution_id: execution.execution_id, agent_id: execution.agent_id,
-            status: execution.status, phase: execution.phase,
-            result_ref: execution.result_ref, error_ref: execution.error_ref,
-            result: execution.result_ref && @repositories.contents.fetch_text(execution.result_ref),
-            error: execution.error_ref && @repositories.contents.fetch_json(execution.error_ref)
-          }.then { |value| Phronomy::Values::Immutable.copy(value) }
-        end
-
-        def handoff_result(execution_id, main_agent_id: nil)
-          anchor = main_agent_id&.to_s
-          seen = {}
-          current = execution_id.to_s
-          reserved_agent_id = nil
-          loop do
-            raise Phronomy::Storage::SerializationError, "Cyclic durable Handoff chain" if seen[current]
-            seen[current] = true
-            begin
-              execution = @repositories.executions.load(current)
-            rescue Phronomy::Storage::NotFoundError
-              routing = @repositories.handoff_states.load(anchor)
-              if routing && Array(routing.metadata["cancelled_execution_ids"]).include?(current)
-                return {execution_id: current, agent_id: reserved_agent_id, status: :cancelled, result: nil, error: nil}.freeze
-              end
-              if reserved_agent_id && routing && routing.phase != "stable" && routing.pending_target_execution_id == current
-                return {execution_id: current, agent_id: reserved_agent_id, status: :active,
-                        phase: :target_pending, reserved: true, result: nil, error: nil}.freeze
-              end
-              raise
-            end
-            anchor ||= execution.metadata.dig("coordination", "main_agent_id")
-            unless anchor && execution.metadata.dig("coordination", "main_agent_id") == anchor
-              raise Phronomy::Storage::ConflictError, "Execution does not belong to this Handoff anchor"
-            end
-            return @repositories.execution_result(current) unless execution.status == :handed_off
-            reserved_agent_id = execution.metadata.fetch("handoff_target_agent_id")
-            current = execution.metadata.fetch("handoff_target_execution_id")
-          end
-        end
-
-        def list_executions(agent_id, after: nil, limit: 100)
-          @repositories.executions.list(agent_id, after: after, limit: limit)
-        end
-      end
-    end
-  end
-end

data/lib/phronomy/agent/selection/candidate.rb

@@ -1,53 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Agent
-    module Selection
-      Candidate = Data.define(
-        :candidate_id,
-        :source_kind,
-        :category,
-        :role,
-        :content_ref,
-        :record_id,
-        :agent_id,
-        :execution_id,
-        :llm_call_id,
-        :tool_call_id,
-        :sequence,
-        :constraint,
-        :priority,
-        :metadata
-      ) do
-        def initialize(**values)
-          effective_constraint = values[:constraint] ||
-            Constraint.selectable(origin: :context_policy)
-          unless effective_constraint.is_a?(Constraint)
-            raise ArgumentError,
-              "Selection::Candidate constraint must be Selection::Constraint"
-          end
-
-          normalized = values.merge(
-            candidate_id: values.fetch(:candidate_id).to_s.freeze,
-            source_kind: values.fetch(:source_kind).to_sym,
-            category: values.fetch(:category).to_sym,
-            role: values[:role]&.to_sym,
-            content_ref: values.fetch(:content_ref).to_s.freeze,
-            record_id: values[:record_id]&.to_s&.freeze,
-            agent_id: values[:agent_id]&.to_s&.freeze,
-            execution_id: values[:execution_id]&.to_s&.freeze,
-            llm_call_id: values[:llm_call_id]&.to_s&.freeze,
-            tool_call_id: values[:tool_call_id]&.to_s&.freeze,
-            sequence: values[:sequence] && Integer(values[:sequence]),
-            constraint: effective_constraint,
-            priority: Integer(values[:priority] || 0),
-            metadata: Phronomy::Values::Immutable.copy(values[:metadata] || {})
-          )
-
-          super(**normalized)
-          freeze
-        end
-      end
-    end
-  end
-end

data/lib/phronomy/agent/selection/constraint.rb

@@ -1,49 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Agent
-    module Selection
-      CONSTRAINT_MODES = %i[required selectable forbidden].freeze
-
-      Constraint = Data.define(:mode, :origin, :reason) do
-        def initialize(mode:, origin:, reason: nil)
-          normalized_mode = mode.to_sym
-          unless CONSTRAINT_MODES.include?(normalized_mode)
-            raise ArgumentError, "unknown Selection constraint mode: #{mode.inspect}"
-          end
-
-          super(
-            mode: normalized_mode,
-            origin: origin.to_sym,
-            reason: reason&.to_s&.freeze
-          )
-          freeze
-        end
-
-        def required?
-          mode == :required
-        end
-
-        def selectable?
-          mode == :selectable
-        end
-
-        def forbidden?
-          mode == :forbidden
-        end
-
-        def self.required(origin:, reason: nil)
-          new(mode: :required, origin: origin, reason: reason)
-        end
-
-        def self.selectable(origin:, reason: nil)
-          new(mode: :selectable, origin: origin, reason: reason)
-        end
-
-        def self.forbidden(origin:, reason: nil)
-          new(mode: :forbidden, origin: origin, reason: reason)
-        end
-      end
-    end
-  end
-end

data/lib/phronomy/agent/tool_execution/tool_call_intercepted.rb

@@ -1,29 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Agent
-    # Normal control-transfer signal raised before RubyLLM executes a Tool Call.
-    #
-    # RubyLLM 2.0 guarantees that the complete assistant message has already
-    # been added to Chat#messages before after_message runs. Keeping that
-    # message here allows Phronomy to persist the complete Provider outcome even
-    # though the RubyLLM call itself unwinds through this exception.
-    # @api private
-    class ToolCallIntercepted < StandardError
-      attr_reader :tool_calls, :assistant_message, :assistant_outcome, :llm_call_id
-
-      def initialize(tool_calls, assistant_message: nil, assistant_outcome: nil, llm_call_id: nil)
-        @tool_calls = Array(tool_calls).freeze
-        @assistant_message = assistant_message
-        @assistant_outcome = assistant_outcome || ProviderCallOutcome.capture(assistant_message)
-        @llm_call_id = llm_call_id&.to_s&.freeze
-        names = @tool_calls.map(&:name).join(", ")
-        super("Tool call intercepted: #{names}")
-      end
-
-      def tool_call
-        @tool_calls.first
-      end
-    end
-  end
-end

data/lib/phronomy/agent/tool_execution/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/configuration.rb

@@ -1,68 +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
-
-    DEFAULT_FACTORIES = {}
-    private_constant :DEFAULT_FACTORIES
-
-    # Bind fresh-instance factories once during application loading. Concrete
-    # component selection belongs to runtime_composition, not configuration.
-    # Applications replace instances through the existing configuration writers.
-    # @api private
-    def self.install_default_factories(tracer:, llm_adapter:)
-      DEFAULT_FACTORIES.replace(tracer: tracer, llm_adapter: llm_adapter).freeze
-      nil
-    end
-
-    attr_accessor :default_model
-    attr_accessor :default_embedding_model
-    attr_accessor :tracer
-    attr_accessor :before_llm_input
-    attr_accessor :recursion_limit
-    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 = DEFAULT_FACTORIES.fetch(:tracer).call
-      @trace_pii = false
-      @event_loop_stop_grace_seconds = 5
-      @llm_adapter = DEFAULT_FACTORIES.fetch(:llm_adapter).call
-      @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/configuration/global_configuration.rb

@@ -1,26 +0,0 @@
-# frozen_string_literal: true
-
-# Global configuration access, replacement, and scoped overrides.
-# Explicitly loaded by the application entry point; not a common definition.
-module Phronomy
-  class << self
-    def configuration
-      @configuration ||= Configuration.new
-    end
-
-    def configure
-      yield configuration
-    end
-
-    def reset_configuration!
-      @configuration = Configuration.new
-    end
-
-    def with_configuration
-      original = @configuration&.dup
-      yield configuration
-    ensure
-      @configuration = original
-    end
-  end
-end