phronomy 0.26.0 → 0.28.0

data/lib/phronomy/agent/handoff_execution_coordinator.rb

@@ -1,143 +0,0 @@
-# frozen_string_literal: true
-
-require "digest"
-
-module Phronomy
-  module Agent
-    # Handoff-aware specialization of the normal Agent execution coordinator.
-    # It changes only the durable terminal semantics of an invocation that
-    # produced a typed HandoffRequest. EventLoop ownership/apply remains entirely
-    # in Agent::ExecutionCoordinator.
-    class HandoffExecutionCoordinator < Phronomy::Agent::ExecutionCoordinator
-      private
-
-      def compute_terminal(operation)
-        view = operation.terminal_view
-        if view.callback_failure
-          return commit_failed_outcome(
-            operation,
-            view.callback_failure.to_stream_callback_error
-          )
-        end
-        error = view.source_error || view.block_error || view.invocation_error
-        raise error if error.is_a?(Phronomy::ExecutionRehydrationRequiredError)
-        return commit_failed_outcome(operation, error) if error
-        return commit_suspended(operation) if view.phase == :suspended
-
-        raise view.block_error if view.input_blocked || view.output_blocked
-        raise view.invocation_error if view.invocation_error
-
-        return commit_handed_off(operation) if view.handoff
-
-        commit_completed(operation)
-      rescue => caught
-        reconcile_terminal_error(operation, caught)
-      end
-
-      def commit_handed_off(operation)
-        current = operation.execution
-        root = operation.root
-        runtime_snapshot = operation.runtime_snapshot
-        request = operation.terminal_view.handoff
-        handed_off = next_root = appended = nil
-
-        @agent.persistence.transaction do |tx|
-          coordination = current.metadata.fetch("coordination")
-          main_id = coordination.fetch("main_agent_id")
-          routing = tx.handoff_states.load(main_id)
-          unless routing && routing.active_agent_id == @agent.agent_id && routing.handoff_revision == coordination.fetch("handoff_revision")
-            raise Phronomy::Persistence::ConflictError, "Handoff routing changed before Source transfer"
-          end
-          if Array(routing.metadata["cancelled_execution_ids"]).include?(current.execution_id)
-            raise Phronomy::CancellationError, "Handoff Source turn was cancelled"
-          end
-          manifest = RecoverySupport.manifest_from_ref(@agent, current.metadata.fetch("manifest_ref"))
-          context = HandoffProjection.new.build_terminal(view: request, manifest: manifest,
-            persistence: tx, source_agent_id: @agent.agent_id)
-          context_ref = tx.contents.put_json(context.to_h)
-          target_id = "handoff-target-#{Digest::SHA256.hexdigest([current.execution_id, request.target_agent_id].join("\0"))}"
-          target_root = tx.agents.load(request.target_agent_id)
-          target_definition = {"id" => target_root.agent_definition_id, "version" => target_root.agent_definition_version}
-          transfer = routing.with(active_agent_id: request.target_agent_id,
-            active_handoff_context_ref: context_ref, phase: "target_pending",
-            pending_source_execution_id: current.execution_id, pending_target_execution_id: target_id,
-            metadata: routing.metadata.merge("target_definition" => target_definition))
-          tx.handoff_states.save(main_id, expected_revision: routing.handoff_revision, state: transfer)
-          encoded_records, call_records = encode_runtime_records(
-            current,
-            tx: tx,
-            snapshot: runtime_snapshot,
-            context_candidate: false,
-            agent_root: root
-          )
-          audit_ref = tx.contents.put_json(
-            "target_agent_id" => request.target_agent_id,
-            "responsibility" => request.responsibility,
-            "selection_intent" => request.selection_intent.to_h do |category, included|
-              [category.to_s, included]
-            end
-          )
-          audit_record = Phronomy::Agent::JournalRecord.new(
-            agent_id: @agent.agent_id,
-            execution_id: current.execution_id,
-            llm_call_id: request.llm_call_id,
-            kind: :execution_handed_off,
-            channel: :audit,
-            content_ref: audit_ref,
-            context_generation: root.transcript_generation,
-            context_candidate: false,
-            metadata: {
-              "target_agent_id" => request.target_agent_id,
-              "handoff_tool_call_id" => request.tool_call_id
-            }.compact
-          )
-
-          all_records = current.working_records + encoded_records + [audit_record]
-          appended = tx.journals.append(
-            root.agent_id,
-            expected_position: root.journal_position,
-            records: all_records
-          )
-          handed_off = current.with(
-            status: :handed_off,
-            phase: :handed_off,
-            working_records: [],
-            llm_calls: current.llm_calls + call_records,
-            approval_request: nil,
-            terminal_reason: "handed_off",
-            metadata: current.metadata.merge("handoff_target_agent_id" => request.target_agent_id,
-              "handoff_target_execution_id" => target_id, "handoff_context_ref" => context_ref)
-          )
-          tx.executions.save(
-            current.execution_id,
-            expected_revision: current.execution_revision,
-            execution: handed_off
-          )
-          context_changed = appended.any?(&:context_candidate)
-          next_root = root.with(
-            agent_revision: root.agent_revision + 1,
-            context_revision: root.context_revision + (context_changed ? 1 : 0),
-            journal_position: root.journal_position + appended.length,
-            lifecycle_status: :idle
-          )
-          tx.agents.save(
-            root.agent_id,
-            expected_revision: root.agent_revision,
-            root: next_root
-          )
-        end
-
-        result = result_base(handed_off, next_root)
-        TerminalOutcome.new(
-          type: :handed_off,
-          execution: handed_off,
-          root: next_root,
-          appended_records: Array(appended).freeze,
-          result: result.freeze,
-          error: nil,
-          approval_request: nil
-        )
-      end
-    end
-  end
-end

data/lib/phronomy/agent/handoff_request.rb

@@ -1,45 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Agent
-    # Typed private control request produced from one intercepted Handoff capability.
-    # @api private
-    HandoffRequest = Data.define(
-      :handoff, :responsibility, :selection_intent, :llm_call_id, :tool_call_id
-    ) do
-      def initialize(handoff:, responsibility:, selection_intent:, llm_call_id: nil, tool_call_id: nil)
-        responsibility = responsibility.to_s.strip
-        raise ArgumentError, "Handoff responsibility must not be empty" if responsibility.empty?
-        unless handoff.is_a?(Handoff)
-          raise ArgumentError, "handoff must be a Phronomy::Agent::Handoff"
-        end
-
-        normalized = handoff.policy.selectable_categories.to_h do |category|
-          raw = selection_intent.fetch(category) do
-            handoff.policy.default_include?(category)
-          end
-          unless raw == true || raw == false
-            raise ArgumentError,
-              "Handoff selection for #{category.inspect} must be boolean"
-          end
-          [category, raw]
-        end.freeze
-
-        unknown = selection_intent.keys.map(&:to_sym) - handoff.policy.selectable_categories
-        unless unknown.empty?
-          raise ArgumentError,
-            "Handoff selection attempts to override non-selectable categories: #{unknown.inspect}"
-        end
-
-        super(
-          handoff: handoff,
-          responsibility: responsibility.freeze,
-          selection_intent: normalized,
-          llm_call_id: llm_call_id&.to_s&.freeze,
-          tool_call_id: tool_call_id&.to_s&.freeze
-        )
-        freeze
-      end
-    end
-  end
-end

data/lib/phronomy/agent/handoff_runner.rb

@@ -1,178 +0,0 @@
-# frozen_string_literal: true
-
-require "time"
-
-module Phronomy
-  module Agent
-    # Durable Agent-domain responsibility routing within one Persistence instance.
-    # @api public
-    class HandoffRunner
-      MAX_HANDOFFS = 20
-
-      # @api public
-      attr_reader :main_agent, :handoffs
-
-      # @api public
-      def initialize(main_agent:, handoffs: [])
-        @main_agent, @handoffs = main_agent, Array(handoffs).freeze
-        @persistence = main_agent.persistence
-        raise ArgumentError, "handoffs must contain Agent::Handoff" unless @handoffs.all? { |h| h.is_a?(Handoff) }
-        @agents = ([main_agent] + @handoffs.flat_map { |edge| [edge.source_agent, edge.target_agent] }).uniq.to_h { |a| [a.agent_id, a] }.freeze
-        unless @agents.values.all? { |a| a.persistence.equal?(@persistence) }
-          raise Phronomy::ConfigurationError, "Durable Handoff graph requires one Persistence instance"
-        end
-        if @handoffs.group_by { |h| [h.source_agent.agent_id, h.target_agent.agent_id] }.any? { |_, edges| edges.size > 1 }
-          raise ArgumentError, "Duplicate Source/Target Handoff edges"
-        end
-        @bindings = @handoffs.group_by { |h| h.source_agent.agent_id }.transform_values { |edges| edges.map { |h| HandoffCapabilityFactory.build(h) }.freeze }.freeze
-        @runtime = Phronomy::Runtime.instance
-      end
-
-      # @api public
-      def invoke(input, config: {})
-        trace_handle = Phronomy::Tracing::Automatic.start("multi_agent.turn",
-          input: input, main_agent_id: main_agent.agent_id,
-          **main_agent.send(:_build_caller_meta, config))
-        operation_error = result = nil
-        if Phronomy::Runtime.in_event_loop_context?
-          raise Phronomy::EventLoopReentrancyError, "HandoffRunner#invoke cannot block EventLoop"
-        end
-        unless Phronomy::Runtime.instance.equal?(@runtime)
-          raise Phronomy::RuntimeShutdownError, "HandoffRunner belongs to a previous Runtime"
-        end
-        config = config.merge(cancellation_token: config[:cancellation_token] || Phronomy::Concurrency::CancellationToken.new)
-        @runtime.__admit_multi_agent(main_agent)
-        admitted = true
-        state = load_state
-        count = 0
-        loop do
-          active = @agents.fetch(state.active_agent_id) do
-            raise Phronomy::ExecutionRehydrationRequiredError, "Handoff graph lacks active Agent #{state.active_agent_id}"
-          end
-          context = state.active_handoff_context_ref && HandoffContext.from_h(@persistence.contents.fetch_json(state.active_handoff_context_ref))
-          wiring = config.merge(phronomy_handoff_bindings: @bindings.fetch(active.agent_id, []),
-            phronomy_handoff_context: context,
-            phronomy_coordination: {"kind" => "handoff", "main_agent_id" => main_agent.agent_id, "handoff_revision" => state.handoff_revision}).freeze
-          active.instance_variable_set(:@_phronomy_coordination_config, wiring)
-          result = if state.phase == "stable"
-            unfinished = @persistence.executions.list_active(active.agent_id)
-            if unfinished.empty?
-              active.invoke(input, config: wiring)
-            else
-              exact = unfinished.fetch(0)
-              unless unfinished.size == 1 && exact.metadata.dig("coordination", "main_agent_id") == main_agent.agent_id
-                raise Phronomy::Persistence::ConflictError, "Active Agent execution belongs to another coordination turn"
-              end
-              wiring[:cancellation_token].cancel! if Array(state.metadata["cancelled_execution_ids"]).include?(exact.execution_id)
-              stored_input = @persistence.contents.fetch_text(exact.metadata.fetch("current_input_ref"))
-              ExactExecution.start(agent: active, execution_id: exact.execution_id, input: stored_input, config: wiring).wait_result
-            end
-          else
-            source = @persistence.executions.load(state.pending_source_execution_id)
-            unless @handoffs.any? { |edge| edge.source_agent.agent_id == source.agent_id && edge.target_agent.agent_id == state.active_agent_id }
-              raise Phronomy::ExecutionRehydrationRequiredError, "Handoff graph lacks committed Source/Target edge"
-            end
-            definition = state.metadata.fetch("target_definition")
-            unless active.class.agent_definition == definition.transform_keys(&:to_sym)
-              raise Phronomy::ConfigurationError, "Handoff Target definition mismatch"
-            end
-            wiring[:cancellation_token].cancel! if Array(state.metadata["cancelled_execution_ids"]).include?(state.pending_target_execution_id)
-            ExactExecution.start(agent: active, execution_id: state.pending_target_execution_id,
-              input: context.responsibility, config: wiring).wait_result
-          end
-          execution = @persistence.executions.load(result.fetch(:execution_id))
-          if execution.status == :handed_off
-            count += 1
-            raise Phronomy::HandoffError, "Exceeded maximum Handoffs in one turn" if count > MAX_HANDOFFS
-            state = @persistence.handoff_states.load(main_agent.agent_id)
-            next
-          end
-          if execution.active?
-            raise Phronomy::ExecutionRehydrationRequiredError, "Handoff execution requires approval or recovery"
-          end
-          raise RecoverySupport.error_from_failure(result[:error]) if result[:error]
-          return result.reject { |key, _| key.to_s.start_with?("_phronomy_") || key == :handoff_request }.merge(agent: active)
-        end
-      rescue Phronomy::CancellationError => error
-        operation_error = error
-        cancel(state.pending_source_execution_id) if state && state.phase != "stable"
-        raise
-      rescue => error
-        operation_error = error
-        raise
-      ensure
-        @runtime.__release_multi_agent(main_agent) if admitted
-        Phronomy::Tracing::Automatic.finish(trace_handle, output: result && result[:output], error: operation_error)
-      end
-
-      # Durably scopes cancellation to an exact turn, including a transferred
-      # Target reservation. A completed older turn never cancels a later turn.
-      # @api public
-      def cancel(execution_id)
-        if Phronomy::Runtime.in_event_loop_context?
-          raise Phronomy::EventLoopReentrancyError, "HandoffRunner#cancel cannot block EventLoop"
-        end
-        intended = leaf = leaf_id = nil
-        begin
-          @persistence.transaction do |tx|
-            first = tx.executions.load(execution_id)
-            unless first.metadata.dig("coordination", "main_agent_id") == main_agent.agent_id
-              raise Phronomy::Persistence::ConflictError, "Execution does not belong to this Handoff anchor"
-            end
-            leaf = first
-            leaf_id = first.execution_id
-            seen = {}
-            while leaf&.status == :handed_off
-              raise Phronomy::Persistence::SerializationError, "Cyclic Handoff chain" if seen[leaf_id]
-              seen[leaf_id] = true
-              leaf_id = leaf.metadata.fetch("handoff_target_execution_id")
-              begin
-                leaf = tx.executions.load(leaf_id)
-              rescue Phronomy::Persistence::NotFoundError
-                leaf = nil
-              end
-            end
-            next if leaf&.terminal?
-            routing = tx.handoff_states.load(main_agent.agent_id)
-            unless routing && (leaf ? routing.active_agent_id == leaf.agent_id : routing.pending_target_execution_id == leaf_id)
-              raise Phronomy::Persistence::ConflictError, "Handoff routing no longer owns the requested turn"
-            end
-            ids = (Array(routing.metadata["cancelled_execution_ids"]) + [leaf_id]).uniq
-            intended = routing.with(phase: leaf ? routing.phase : "stable",
-              metadata: routing.metadata.merge("cancelled_execution_ids" => ids))
-            tx.handoff_states.save(main_agent.agent_id, expected_revision: routing.handoff_revision, state: intended)
-          end
-        rescue => error
-          confirmed = @persistence.handoff_states.load(main_agent.agent_id)
-          raise error unless intended && confirmed && Array(confirmed.metadata["cancelled_execution_ids"]).include?(leaf_id)
-        end
-        return @persistence.execution_result(leaf_id) if leaf&.terminal?
-        ExecutionCancellation.signal(leaf_id, leaf.agent_id) if leaf&.active?
-        {execution_id: leaf_id, cancellation_requested: !leaf&.terminal?}.freeze
-      end
-
-      # Reads a specified source/Target chain without current graph continuation.
-      # @api public
-      def result(execution_id)
-        @persistence.handoff_result(execution_id, main_agent_id: main_agent.agent_id)
-      end
-
-      private
-
-      def load_state
-        state = @persistence.handoff_states.load(main_agent.agent_id)
-        return state if state
-        now = Time.now.utc.iso8601(6)
-        initial = HandoffState.new(main_agent_id: main_agent.agent_id, handoff_revision: 1,
-          active_agent_id: main_agent.agent_id, active_handoff_context_ref: nil,
-          phase: "stable", pending_source_execution_id: nil, pending_target_execution_id: nil,
-          created_at: now, updated_at: now, metadata: {})
-        @persistence.transaction { |tx| tx.handoff_states.save(main_agent.agent_id, expected_revision: nil, state: initial) }
-      rescue => error
-        confirmed = @persistence.handoff_states.load(main_agent.agent_id)
-        raise error unless confirmed
-        confirmed
-      end
-    end
-  end
-end

data/lib/phronomy/agent/phase_machine_builder.rb

@@ -1,152 +0,0 @@
-# frozen_string_literal: true
-
-require "state_machines"
-
-module Phronomy
-  module Agent
-    class PhaseMachineBuilder
-      TOOL_EVENTS = %i[
-        tool_authorized
-        tool_approval_required
-        tool_completed
-        tool_failed
-        tool_rejected
-        tool_cancelled
-      ].freeze
-
-      def initialize(entry_actions: {})
-        @entry_actions = entry_actions
-      end
-
-      def build
-        entry_actions = @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 :filtering_input
-            state :building_context
-            state :calling_llm
-            state :starting_tools
-            state :evaluating_tools
-            state :waiting_for_tools
-            state :dispatching_tools
-            state :recording_tool_results
-            state :suspended
-            state :output_filtering
-            state :handed_off
-            state :completed
-            state :blocked
-            state :failed
-
-            event :state_completed do
-              transition idle: :filtering_input
-
-              transition filtering_input: :building_context,
-                if: ->(machine) { machine.context&.input_passed? }
-              transition filtering_input: :blocked,
-                if: ->(machine) { machine.context&.input_blocked? }
-
-              transition building_context: :calling_llm
-              transition starting_tools: :evaluating_tools
-
-              transition evaluating_tools: :failed,
-                if: ->(machine) { machine.context&.tool_batch_failed? }
-              transition evaluating_tools: :blocked,
-                if: ->(machine) { machine.context&.tool_batch_rejected? }
-              transition evaluating_tools: :recording_tool_results,
-                if: ->(machine) { machine.context&.tool_batch_completed? }
-              transition evaluating_tools: :suspended,
-                if: ->(machine) { machine.context&.approval_required? }
-              transition evaluating_tools: :dispatching_tools,
-                if: ->(machine) { machine.context&.ready_to_dispatch? }
-              transition evaluating_tools: :waiting_for_tools
-
-              transition recording_tool_results: :calling_llm
-
-              transition output_filtering: :completed,
-                if: ->(machine) { machine.context&.output_passed? }
-              transition output_filtering: :blocked,
-                if: ->(machine) { machine.context&.output_blocked? }
-            end
-
-            event :llm_completed do
-              transition calling_llm: :failed,
-                if: ->(machine) { machine.context&.callback_failed? }
-              transition calling_llm: :failed,
-                if: ->(machine) { machine.context&.handoff_failed? }
-              transition calling_llm: :handed_off,
-                if: ->(machine) { machine.context&.handoff_requested? }
-              transition calling_llm: :starting_tools,
-                if: ->(machine) { machine.context&.tool_call_pending? }
-              transition calling_llm: :output_filtering
-            end
-
-            event :llm_failed do
-              transition calling_llm: :failed
-            end
-
-            event :llm_setup_failed do
-              transition calling_llm: :failed
-            end
-
-            event :tool_setup_failed do
-              transition dispatching_tools: :failed
-            end
-
-            event :tool_dispatch_prepared do
-              transition dispatching_tools: :evaluating_tools
-            end
-
-            TOOL_EVENTS.each do |event_name|
-              event event_name do
-                transition waiting_for_tools: :evaluating_tools
-              end
-            end
-
-            event :resume do
-              transition suspended: :waiting_for_tools
-            end
-
-            event :application_callback_failed do
-              transition filtering_input: :failed
-              transition building_context: :failed
-              transition calling_llm: :failed
-              transition starting_tools: :failed
-              transition evaluating_tools: :failed
-              transition waiting_for_tools: :failed
-              transition dispatching_tools: :failed
-              transition recording_tool_results: :failed
-              transition output_filtering: :failed
-            end
-
-            entry_actions.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
-
-      def build_entry_callback(callable, state_name)
-        ->(machine) {
-          result = callable.call(machine.context)
-          if result.is_a?(Phronomy::TaskResult)
-            raise Phronomy::InvalidAsyncEntryActionError,
-              "Agent entry action for #{state_name.inspect} returned Phronomy::TaskResult"
-          end
-          machine.context = result if result.respond_to?(:set_graph_metadata)
-        }
-      end
-    end
-  end
-end

data/lib/phronomy/agent/provider_call_outcome.rb

@@ -1,106 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Agent
-    # Immutable, Phronomy-owned snapshot of one completed Provider assistant output.
-    ProviderCallOutcome = Data.define(:role, :content, :tool_calls, :usage, :metadata) do
-      def self.capture(message)
-        return if message.nil?
-        return message if message.is_a?(self)
-
-        calls = if message.respond_to?(:tool_calls) && message.tool_calls
-          source = message.tool_calls.respond_to?(:values) ? message.tool_calls.values : Array(message.tool_calls)
-          source.map { |call| normalize(tool_call_hash(call)) }
-        else
-          []
-        end
-        usage = if message.respond_to?(:tokens) && message.tokens
-          normalize(message.tokens.respond_to?(:to_h) ? message.tokens.to_h : message.tokens)
-        else
-          {}
-        end
-        metadata = {}
-        metadata["model_id"] = message.model_id.to_s if message.respond_to?(:model_id) && message.model_id
-
-        new(
-          role: message.respond_to?(:role) ? message.role : :assistant,
-          content: normalize(message.respond_to?(:content) ? message.content : nil),
-          tool_calls: calls,
-          usage: usage,
-          metadata: metadata
-        )
-      end
-
-      def self.from_h(hash)
-        source = hash.to_h { |key, value| [key.to_s, value] }
-        new(
-          role: source.fetch("role", "assistant"),
-          content: source["content"],
-          tool_calls: source.fetch("tool_calls", []),
-          usage: source.fetch("usage", {}),
-          metadata: source.fetch("metadata", {})
-        )
-      end
-
-      def self.tool_call_hash(call)
-        return call.to_h if call.respond_to?(:to_h)
-
-        {
-          "id" => call.respond_to?(:id) ? call.id : nil,
-          "name" => call.respond_to?(:name) ? call.name : nil,
-          "arguments" => call.respond_to?(:arguments) ? call.arguments : {}
-        }.compact
-      end
-      private_class_method :tool_call_hash
-
-      def self.normalize(value)
-        case value
-        when Hash
-          value.to_h { |key, child| [key.to_s, normalize(child)] }
-        when Array
-          value.map { |child| normalize(child) }
-        when Symbol
-          value.to_s
-        when String, Integer, Float, TrueClass, FalseClass, NilClass
-          value
-        else
-          value.respond_to?(:to_h) ? normalize(value.to_h) : value.to_s
-        end
-      end
-      private_class_method :normalize
-
-      def initialize(role:, content:, tool_calls:, usage: {}, metadata: {})
-        super(
-          role: role&.to_sym,
-          content: Immutable.copy(content),
-          tool_calls: Immutable.copy(Array(tool_calls)),
-          usage: Immutable.copy(usage || {}),
-          metadata: Immutable.copy(metadata || {})
-        )
-        Immutable.validate_canonical_json!(content, label: "Provider assistant content")
-        Immutable.validate_canonical_json!(tool_calls, label: "Provider Tool Calls")
-        Immutable.validate_canonical_json!(usage, label: "Provider usage")
-        Immutable.validate_canonical_json!(metadata, label: "Provider outcome metadata")
-        freeze
-      end
-
-      def to_h
-        {
-          "role" => role&.to_s,
-          "content" => content,
-          "tool_calls" => tool_calls,
-          "usage" => usage,
-          "metadata" => metadata
-        }.compact
-      end
-
-      def content_present?
-        !content.nil? && !(content.respond_to?(:empty?) && content.empty?)
-      end
-
-      def tool_call?
-        !tool_calls.empty?
-      end
-    end
-  end
-end