phronomy 0.27.0 → 0.28.0

data/lib/phronomy/agent/context_assembly/runtime_chat_builder.rb

@@ -1,36 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Agent
-    # Constructs provider chat objects from already selected model settings.
-    # Agent hooks retain projection installation and invocation-specific Tools.
-    # @api private
-    class RuntimeChatBuilder
-      def self.build(config)
-        chat = RubyLLM.chat(**chat_options(config))
-        chat.with_temperature(config["temperature"]) if config["temperature"]
-        if config["max_output_tokens"]
-          chat.with_max_output_tokens(config["max_output_tokens"])
-        end
-        chat
-      end
-
-      def self.apply_instructions(chat, text, cache:, provider:)
-        chat.with_instructions(text, cache_until_here: cache)
-      end
-
-      def self.chat_options(config)
-        opts = {}
-        model = config["model"]
-        opts[:model] = model if model
-        provider = config["provider"]
-        if provider
-          opts[:provider] = provider.to_sym
-          opts[:assume_model_exists] = true
-        end
-        opts
-      end
-      private_class_method :chat_options
-    end
-  end
-end

data/lib/phronomy/agent/context_assembly/token_budget_resolver.rb

@@ -1,22 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Agent
-    # Resolves the input limit from RubyLLM's authoritative model registry.
-    class TokenBudgetResolver
-      def resolve(model_config)
-        config = model_config.to_h.transform_keys(&:to_s)
-        model_name = config["model"]
-        return nil unless model_name
-
-        model = RubyLLM.models.find(model_name, provider: config["provider"])
-        limit = model&.context_window
-        return nil unless limit.is_a?(Integer) && limit.positive?
-
-        Phronomy::LlmContextWindow::TokenBudget.new(max_input_tokens: limit)
-      rescue RubyLLM::ModelNotFoundError
-        nil
-      end
-    end
-  end
-end

data/lib/phronomy/agent/context_parts/validators/final_budget_validator.rb

@@ -1,37 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Agent
-    module ContextParts
-      module Validators
-        class FinalBudgetValidator
-          def initialize(content_loader:)
-            @content_loader = content_loader
-          end
-
-          def validate!(token_budget:, segments:, extra_values: [])
-            return 0 unless token_budget
-
-            estimated = Array(segments).sum do |segment|
-              Phronomy::LlmContextWindow::TokenEstimator.estimate(
-                @content_loader.call(segment.fetch(:content_ref))
-              )
-            end
-            estimated += Array(extra_values).sum do |value|
-              bytes = value.is_a?(String) ? value : Phronomy::CanonicalJSON.dump(value)
-              Phronomy::LlmContextWindow::TokenEstimator.estimate(bytes)
-            end
-
-            limit = token_budget.effective_input_limit
-            if estimated > limit
-              raise Phronomy::ContextBudgetExceededError,
-                "Canonical LLM input (estimated #{estimated} tokens) exceeds " \
-                "available input budget (#{limit} tokens)"
-            end
-            estimated
-          end
-        end
-      end
-    end
-  end
-end

data/lib/phronomy/agent/context_policies/default.rb

@@ -1,142 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Agent
-    module ContextPolicies
-      class Default < ContextPolicy
-        CONVERSATION_SHARE = 0.60
-
-        def self.instance
-          @instance ||= new.freeze
-        end
-
-        def call(input)
-          unless input.is_a?(ContextPolicyInput)
-            raise ArgumentError, "Default ContextPolicy expected ContextPolicyInput"
-          end
-
-          return all_context(input) unless input.token_budget
-
-          limit = input.token_budget.effective_input_limit
-          required_knowledge = input.knowledge.select(&:required?)
-          optional_knowledge = input.knowledge.reject(&:required?)
-          required_conversation = input.conversation.select { |group| group.any?(&:required?) }
-          optional_conversation = input.conversation.reject { |group| group.any?(&:required?) }
-
-          fixed_cost = item_cost(input.instruction) + item_cost(input.tools) +
-            item_cost(required_knowledge) + group_cost(required_conversation)
-          if fixed_cost > limit
-            raise Phronomy::ContextBudgetExceededError,
-              "Required Context (estimated #{fixed_cost} tokens) exceeds " \
-              "available input budget (#{limit} tokens)"
-          end
-
-          remaining = limit - fixed_cost
-          conversation_budget = (remaining * CONVERSATION_SHARE).floor
-          knowledge_budget = remaining - conversation_budget
-
-          selected_conversation, older_conversation, conversation_used =
-            select_recent_suffix(optional_conversation, conversation_budget)
-          selected_knowledge, remaining_knowledge, knowledge_used =
-            select_stable_fit(optional_knowledge, knowledge_budget)
-
-          reusable = remaining - conversation_used - knowledge_used
-          if reusable.positive? && !older_conversation.empty?
-            more_conversation, _, used =
-              select_recent_suffix(older_conversation, reusable)
-            selected_conversation = more_conversation + selected_conversation
-            reusable -= used
-          end
-          if reusable.positive? && !remaining_knowledge.empty?
-            more_knowledge, _remaining_knowledge, used =
-              select_stable_fit(remaining_knowledge, reusable)
-            selected_knowledge += more_knowledge
-            reusable -= used
-          end
-
-          conversation = (required_conversation + selected_conversation)
-            .uniq
-            .sort_by { |group| group_sequence(group) }
-          knowledge_ids = (required_knowledge + selected_knowledge).to_h { |item| [item.id, true] }
-          knowledge = input.knowledge.select { |item| knowledge_ids[item.id] }
-
-          plan(
-            instruction: input.instruction,
-            knowledge: knowledge,
-            tools: input.tools,
-            conversation: conversation,
-            metadata: {
-              "default_policy" => true,
-              "estimated_fixed_tokens" => fixed_cost,
-              "estimated_unused_tokens" => reusable
-            }
-          )
-        end
-
-        private
-
-        def all_context(input)
-          plan(
-            instruction: input.instruction,
-            knowledge: input.knowledge,
-            tools: input.tools,
-            conversation: input.conversation,
-            metadata: {"default_policy" => true}
-          )
-        end
-
-        def item_cost(items)
-          Array(items).sum { |item| Integer(item.estimated_tokens || 0) }
-        end
-
-        def group_cost(groups)
-          Array(groups).sum { |group| item_cost(group) }
-        end
-
-        def group_sequence(group)
-          group.filter_map(&:sequence).min || 0
-        end
-
-        def select_recent_suffix(groups, budget)
-          ordered = Array(groups).sort_by { |group| group_sequence(group) }
-          selected = []
-          remaining = Integer(budget)
-          stop_index = -1
-
-          (ordered.length - 1).downto(0) do |index|
-            cost = item_cost(ordered[index])
-            if cost > remaining
-              stop_index = index
-              break
-            end
-            selected.unshift(ordered[index])
-            remaining -= cost
-          end
-
-          older = if stop_index >= 0
-            ordered[0..stop_index]
-          else
-            []
-          end
-          [selected.freeze, older.freeze, Integer(budget) - remaining]
-        end
-
-        def select_stable_fit(items, budget)
-          remaining = Integer(budget)
-          selected = []
-          unselected = []
-          Array(items).each do |item|
-            cost = Integer(item.estimated_tokens || 0)
-            if cost <= remaining
-              selected << item
-              remaining -= cost
-            else
-              unselected << item
-            end
-          end
-          [selected.freeze, unselected.freeze, Integer(budget) - remaining]
-        end
-      end
-    end
-  end
-end

data/lib/phronomy/agent/execution/phase_machine_builder.rb

@@ -1,101 +0,0 @@
-# frozen_string_literal: true
-
-require "state_machines"
-
-module Phronomy
-  module Agent
-    class PhaseMachineBuilder
-      def initialize(entry_actions: {})
-        @entry_actions = entry_actions
-      end
-
-      def build
-        entry_actions = @entry_actions
-        callback_builder = method(:build_entry_callback)
-        condition_builder = method(:build_transition_condition)
-        external_events = InvocationTransitions::EXTERNAL_EVENTS
-        declared_states = InvocationTransitions::DECLARED_STATES
-        entry_point = InvocationTransitions::ENTRY_POINT
-
-        Class.new do
-          attr_accessor :context, :current_event
-
-          state_machine :phase, initial: entry_point do
-            declared_states.each { |state_name| state state_name }
-
-            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
-
-            external_events.each do |event_name, transitions|
-              event event_name do
-                transitions.each do |definition|
-                  transition(
-                    definition[:from] => definition[:to],
-                    :if => condition_builder.call(definition)
-                  )
-                end
-              end
-            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_transition_condition(definition)
-        guard = definition[:guard]
-        ->(machine) {
-          guard.nil? || (!machine.context.nil? && guard.call(machine.context))
-        }
-      end
-
-      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/execution/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.to_s if message.respond_to?(:model) && message.model
-
-        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: Phronomy::Values::Immutable.copy(content),
-          tool_calls: Phronomy::Values::Immutable.copy(Array(tool_calls)),
-          usage: Phronomy::Values::Immutable.copy(usage || {}),
-          metadata: Phronomy::Values::Immutable.copy(metadata || {})
-        )
-        Phronomy::Values::Immutable.validate_canonical_json!(content, label: "Provider assistant content")
-        Phronomy::Values::Immutable.validate_canonical_json!(tool_calls, label: "Provider Tool Calls")
-        Phronomy::Values::Immutable.validate_canonical_json!(usage, label: "Provider usage")
-        Phronomy::Values::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

data/lib/phronomy/agent/handoff/handoff_execution_coordinator.rb

@@ -1,15 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Agent
-    # Selects Handoff persistence; execution ownership and delivery remain in
-    # ExecutionCoordinator. This is not a public subclass extension contract.
-    class HandoffExecutionCoordinator < Phronomy::Agent::ExecutionCoordinator
-      private
-
-      def build_outcome_committer
-        HandoffOutcomeCommitter.new(agent: @agent, persistence: @agent.persistence)
-      end
-    end
-  end
-end

data/lib/phronomy/agent/handoff/handoff_outcome_committer.rb

@@ -1,131 +0,0 @@
-# frozen_string_literal: true
-
-require "digest"
-
-module Phronomy
-  module Agent
-    # Adds atomic Source transfer while sharing ordinary result persistence.
-    # Outcome selection deliberately retains Handoff-specific precedence.
-    # @api private
-    class HandoffOutcomeCommitter < ExecutionOutcomeCommitter
-      # @api private
-      def commit_outcome(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
-
-      private
-
-      def commit_handed_off(operation)
-        handed_off = next_root = appended = nil
-        @persistence.transaction do |tx|
-          routing = validated_source_routing(tx, operation.execution)
-          context_ref = persist_handoff_context(tx, operation)
-          target_id = transfer_routing(tx, operation, routing, context_ref)
-          records, handed_off = encode_handoff(tx, operation, target_id, context_ref)
-          appended = append_journal(tx, operation.root, records)
-          save_execution(tx, operation.execution, handed_off)
-          next_root = save_terminal_root(tx, operation.root, appended)
-        end
-        Outcome.new(type: :handed_off, execution: handed_off, root: next_root,
-          appended_records: Array(appended).freeze,
-          result: result_base(handed_off, next_root).freeze,
-          error: nil, approval_request: nil)
-      end
-
-      def validated_source_routing(tx, current)
-        coordination = current.metadata.fetch("coordination")
-        routing = tx.handoff_states.load(coordination.fetch("main_agent_id"))
-        unless routing && routing.active_agent_id == @agent.agent_id && routing.handoff_revision == coordination.fetch("handoff_revision")
-          raise Phronomy::Storage::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
-        routing
-      end
-
-      def persist_handoff_context(tx, operation)
-        manifest = SavedContextReader.manifest_from_ref(@agent, operation.execution.metadata.fetch("manifest_ref"))
-        context = HandoffProjection.new.build_terminal(view: operation.terminal_view.handoff,
-          manifest: manifest, persistence: tx, source_agent_id: @agent.agent_id)
-        tx.contents.put_json(context.to_h)
-      end
-
-      def transfer_routing(tx, operation, routing, context_ref)
-        request = operation.terminal_view.handoff
-        target_id = "handoff-target-#{Digest::SHA256.hexdigest([operation.execution.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: operation.execution.execution_id, pending_target_execution_id: target_id,
-          metadata: routing.metadata.merge("target_definition" => target_definition))
-        tx.handoff_states.save(routing.main_agent_id, expected_revision: routing.handoff_revision, state: transfer)
-        target_id
-      end
-
-      def encode_handoff(tx, operation, target_id, context_ref)
-        current = operation.execution
-        request = operation.terminal_view.handoff
-        encoded_records, call_records = encode_runtime_records(tx, operation, context_candidate: false)
-        audit_record = encode_handoff_audit(tx, operation)
-        records = current.working_records + encoded_records + [audit_record]
-        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)
-        )
-        [records, handed_off]
-      end
-
-      def encode_handoff_audit(tx, operation)
-        request = operation.terminal_view.handoff
-        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
-        )
-        JournalRecord.new(
-          agent_id: @agent.agent_id,
-          execution_id: operation.execution.execution_id,
-          llm_call_id: request.llm_call_id,
-          kind: :execution_handed_off,
-          channel: :audit,
-          content_ref: audit_ref,
-          context_generation: operation.root.transcript_generation,
-          context_candidate: false,
-          metadata: {
-            "target_agent_id" => request.target_agent_id,
-            "handoff_tool_call_id" => request.tool_call_id
-          }.compact
-        )
-      end
-    end
-  end
-end

data/lib/phronomy/agent/handoff/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/lifecycle_contract/handoff_error.rb

@@ -1,7 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "../../common/error"
-
-module Phronomy
-  class HandoffError < Error; end
-end