phronomy 0.15.0 → 0.16.0

data/lib/phronomy/agent/context_importer.rb

@@ -0,0 +1,217 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    class ContextImporter
+      ImportedRecord = Data.define(
+        :kind, :channel, :role, :content, :content_format, :metadata
+      ) do
+        def initialize(**values)
+          super(**values.merge(
+            content: Immutable.copy(values[:content]),
+            metadata: Immutable.copy(values[:metadata] || {})
+          ))
+          freeze
+        end
+      end
+
+      ImportedContext = Data.define(:records) do
+        def initialize(records:)
+          super(records: records.freeze)
+          freeze
+        end
+      end
+
+      class << self
+        def import_messages(messages, system_message: :reject)
+          source_messages = Array(messages)
+          validate_protocol!(source_messages)
+          records = source_messages.map do |message|
+            import_message(message, system_message: system_message)
+          end
+          ImportedContext.new(records: records.freeze)
+        end
+
+        private
+
+        # Import validation is defined by the external-message contract, not by
+        # limitations of Phronomy's internal representation. Each supplied
+        # message is one explicit logical message and is journaled without
+        # splitting its assistant content from its Tool Calls.
+        def validate_protocol!(messages)
+          pending = {}
+          seen_tool_call_ids = {}
+
+          messages.each_with_index do |message, index|
+            role = read(message, :role).to_sym
+
+            if pending.any? && role != :tool
+              raise ArgumentError,
+                "message #{index} appears before Tool Results for: #{pending.keys.join(", ")}"
+            end
+
+            case role
+            when :assistant
+              tool_calls_for(message).each do |call|
+                payload = normalize(read_tool_call(call))
+                call_id = payload.fetch("id").to_s
+                raise ArgumentError, "tool_call requires id" if call_id.empty?
+                if seen_tool_call_ids[call_id]
+                  raise ArgumentError, "duplicate tool_call id: #{call_id}"
+                end
+                seen_tool_call_ids[call_id] = true
+                pending[call_id] = true
+              end
+            when :tool
+              call_id = read_optional(message, :tool_call_id).to_s
+              raise ArgumentError, "tool message requires tool_call_id" if call_id.empty?
+              unless pending.delete(call_id)
+                raise ArgumentError, "orphan or duplicate Tool Result: #{call_id}"
+              end
+            when :user, :system
+              # No Tool protocol state is introduced by these roles.
+            else
+              raise ArgumentError, "unsupported message role: #{role.inspect}"
+            end
+          end
+
+          return if pending.empty?
+
+          raise ArgumentError,
+            "imported history ends before Tool Results for: #{pending.keys.join(", ")}"
+        end
+
+        def import_message(message, system_message:)
+          role = read(message, :role).to_sym
+          case role
+          when :system
+            if system_message == :reject
+              raise ArgumentError,
+                "system messages must be imported as explicit instruction segments"
+            end
+            raise ArgumentError,
+              "unsupported system_message policy: #{system_message.inspect}"
+          when :user
+            text_record(:external_message, :external, :user, read(message, :content))
+          when :assistant
+            import_assistant(message)
+          when :tool
+            import_tool_message(message)
+          else
+            raise ArgumentError, "unsupported message role: #{role.inspect}"
+          end
+        end
+
+        def import_assistant(message)
+          calls = tool_calls_for(message).map { |call| normalize(read_tool_call(call)) }
+          content = read_optional(message, :content)
+          content = "" if content.nil? && !calls.empty?
+          if (content.nil? || (content.respond_to?(:empty?) && content.empty?)) && calls.empty?
+            raise ArgumentError,
+              "assistant message requires content or one or more tool_calls"
+          end
+
+          payload = {
+            "role" => "assistant",
+            "content" => normalize(content),
+            "tool_calls" => calls
+          }
+          model_id = read_optional(message, :model_id)
+          payload["model_id"] = model_id.to_s if model_id
+
+          ImportedRecord.new(
+            kind: :assistant_message,
+            channel: :llm,
+            role: :assistant,
+            content: payload,
+            content_format: :json,
+            metadata: assistant_metadata(calls)
+          )
+        end
+
+        def import_tool_message(message)
+          tool_call_id = read_optional(message, :tool_call_id).to_s
+          raise ArgumentError, "tool message requires tool_call_id" if tool_call_id.empty?
+
+          ImportedRecord.new(
+            kind: :tool_message,
+            channel: :tool,
+            role: :tool,
+            content: {
+              "role" => "tool",
+              "content" => String(read(message, :content)),
+              "tool_call_id" => tool_call_id
+            },
+            content_format: :json,
+            metadata: {"tool_call_id" => tool_call_id}
+          )
+        end
+
+        def assistant_metadata(calls)
+          {
+            "tool_call_ids" => calls.map { |call| call.fetch("id").to_s },
+            "tool_names" => calls.map { |call| call.fetch("name").to_s }
+          }
+        end
+
+        def tool_calls_for(message)
+          tool_calls = read_optional(message, :tool_calls)
+          Array(tool_calls.respond_to?(:values) ? tool_calls.values : tool_calls)
+        end
+
+        def text_record(kind, channel, role, content)
+          ImportedRecord.new(
+            kind: kind,
+            channel: channel,
+            role: role,
+            content: String(content),
+            content_format: :text,
+            metadata: {}
+          )
+        end
+
+        def read_tool_call(call)
+          return call.to_h if call.respond_to?(:to_h)
+
+          {
+            id: read(call, :id),
+            name: read(call, :name),
+            arguments: read_optional(call, :arguments) || {},
+            thought_signature: read_optional(call, :thought_signature)
+          }.compact
+        end
+
+        def read(value, name)
+          result = read_optional(value, name)
+          raise ArgumentError, "message is missing #{name}" if result.nil?
+
+          result
+        end
+
+        def read_optional(value, name)
+          return value.public_send(name) if value.respond_to?(name)
+          return value[name] if value.respond_to?(:key?) && value.key?(name)
+          return value[name.to_s] if value.respond_to?(:key?) && value.key?(name.to_s)
+
+          nil
+        end
+
+        def 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) :
+              raise(ArgumentError, "unsupported imported value: #{value.class}")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/agent/context_parts/budget/token_budget_packer.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    module ContextParts
+      module Budget
+        class TokenBudgetPacker
+          def pack(request:, units:)
+            return Array(units).freeze unless request.token_budget
+
+            candidate_index = request.candidates.to_h { |candidate| [candidate.candidate_id, candidate] }
+            mandatory = Integer(request.metadata["mandatory_token_estimate"] || 0)
+            limit = request.token_budget.effective_input_limit
+            if mandatory > limit
+              raise Phronomy::ContextBudgetExceededError,
+                "Mandatory content (estimated #{mandatory} tokens) exceeds " \
+                "available input budget (#{limit} tokens)"
+            end
+
+            remaining = limit - mandatory
+            required, optional = Array(units).partition { |unit| unit.requirement != :optional }
+            required_cost = required.sum { |unit| unit_cost(unit, candidate_index) }
+            if required_cost > remaining
+              raise Phronomy::ContextBudgetExceededError,
+                "Required Context (estimated #{required_cost} tokens) exceeds " \
+                "remaining input budget (#{remaining} tokens after mandatory content)"
+            end
+
+            selected = required.dup
+            remaining -= required_cost
+            optional.each do |unit|
+              cost = unit_cost(unit, candidate_index)
+              next if cost > remaining
+
+              selected << unit
+              remaining -= cost
+            end
+            selected.freeze
+          end
+
+          private
+
+          def unit_cost(unit, candidate_index)
+            unit.candidate_ids.sum do |candidate_id|
+              candidate = candidate_index.fetch(candidate_id)
+              Integer(candidate.metadata["estimated_tokens"] || 0)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/agent/context_parts/requirements/required_context_resolver.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    module ContextParts
+      module Requirements
+        class RequiredContextResolver
+          def resolve(request:, units:)
+            candidates = request.candidates.to_h { |candidate| [candidate.candidate_id, candidate] }
+            declared = request.required_coverage.to_h { |value| [value.to_s, true] }
+            latest_tool_unit = latest_current_tool_unit(request, units, candidates)
+
+            Array(units).map do |unit|
+              requirement = unit.requirement
+              if unit.unit_id == latest_tool_unit&.unit_id
+                requirement = :protocol_required
+              elsif requirement == :optional && unit.candidate_ids.any? do |candidate_id|
+                candidate = candidates.fetch(candidate_id)
+                declared[candidate.candidate_id] || declared[candidate.record_id.to_s]
+              end
+                requirement = :declared_required
+              end
+
+              next unit if requirement == unit.requirement
+
+              ContextSelectionUnit.new(
+                unit_id: unit.unit_id,
+                candidate_ids: unit.candidate_ids,
+                dependency_unit_ids: unit.dependency_unit_ids,
+                kind: unit.kind,
+                requirement: requirement,
+                priority: unit.priority,
+                sequence_range: unit.sequence_range,
+                metadata: unit.metadata
+              )
+            end.freeze
+          end
+
+          private
+
+          def latest_current_tool_unit(request, units, candidates)
+            return unless request.call_mode == :complete
+
+            Array(units).select do |unit|
+              unit.kind == :tool_exchange && unit.candidate_ids.any? do |candidate_id|
+                candidate = candidates.fetch(candidate_id)
+                candidate.source_kind == :working &&
+                  candidate.execution_id.to_s == request.execution_id.to_s
+              end
+            end.max_by { |unit| unit.sequence_range.last }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/agent/context_parts/selectors/recent_first_selector.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    module ContextParts
+      module Selectors
+        class RecentFirstSelector
+          def order(request:, units:)
+            candidates = request.candidates.to_h { |candidate| [candidate.candidate_id, candidate] }
+            Array(units).sort_by do |unit|
+              required_rank = (unit.requirement == :optional) ? 1 : 0
+              current_rank = current_execution_unit?(request, unit, candidates) ? 0 : 1
+              [required_rank, current_rank, -unit.priority, -unit.sequence_range.last]
+            end.freeze
+          end
+
+          private
+
+          def current_execution_unit?(request, unit, candidates)
+            unit.candidate_ids.any? do |candidate_id|
+              candidate = candidates.fetch(candidate_id)
+              candidate.execution_id.to_s == request.execution_id.to_s &&
+                candidate.source_kind == :working
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/agent/context_parts/unit_builders/dependency_aware_unit_builder.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Phronomy
+  module Agent
+    module ContextParts
+      module UnitBuilders
+        class DependencyAwareUnitBuilder
+          def build(candidates)
+            ordered = Array(candidates).sort_by { |candidate| [candidate.sequence || 0, candidate.candidate_id] }
+            by_id = ordered.to_h { |candidate| [candidate.candidate_id, candidate] }
+
+            canonical_assistants = ordered.select { |candidate| candidate.category == :assistant_message }
+            canonical_tool_messages = ordered.select { |candidate| candidate.category == :tool_message }
+              .group_by(&:tool_call_id)
+            assistant_by_tool_call_id = canonical_assistants.each_with_object({}) do |candidate, result|
+              canonical_tool_call_ids(candidate).each do |tool_call_id|
+                if result.key?(tool_call_id)
+                  raise ArgumentError, "duplicate assistant Tool Call id in Context candidates: #{tool_call_id}"
+                end
+                result[tool_call_id] = candidate
+              end
+            end
+
+            legacy_tool_results = ordered.select { |candidate| candidate.category == :tool_result }
+              .group_by(&:tool_call_id)
+            legacy_calls_by_llm = ordered.select do |candidate|
+              candidate.category == :tool_call && candidate.llm_call_id
+            end.group_by(&:llm_call_id)
+            legacy_assistant_by_llm = ordered.select do |candidate|
+              candidate.llm_call_id && %i[llm_message tool_call].include?(candidate.category)
+            end.group_by(&:llm_call_id)
+
+            claimed = Set.new
+            units = []
+            ordered.each_with_index do |candidate, index|
+              next if claimed.include?(candidate.candidate_id)
+
+              group = canonical_tool_exchange(
+                candidate,
+                assistant_by_tool_call_id: assistant_by_tool_call_id,
+                tool_messages: canonical_tool_messages
+              )
+              group ||= if legacy_runtime_tool_exchange?(candidate, legacy_calls_by_llm)
+                legacy_runtime_tool_exchange(
+                  candidate,
+                  assistant_by_llm: legacy_assistant_by_llm,
+                  calls_by_llm: legacy_calls_by_llm,
+                  tool_results: legacy_tool_results
+                )
+              else
+                legacy_import_tool_exchange(ordered, index, legacy_tool_results)
+              end
+
+              if group && !group.empty?
+                group.each { |item| claimed << item.candidate_id }
+                units << build_unit(group, kind: :tool_exchange)
+              else
+                claimed << candidate.candidate_id
+                units << build_unit([by_id.fetch(candidate.candidate_id)], kind: :message)
+              end
+            end
+
+            units.sort_by { |unit| unit.sequence_range.first }.freeze
+          end
+
+          private
+
+          def canonical_tool_exchange(candidate, assistant_by_tool_call_id:, tool_messages:)
+            assistant = if candidate.category == :assistant_message
+              candidate
+            elsif candidate.category == :tool_message
+              assistant_by_tool_call_id[candidate.tool_call_id]
+            end
+            return unless assistant
+
+            call_ids = canonical_tool_call_ids(assistant)
+            return if call_ids.empty?
+
+            messages = call_ids.flat_map { |tool_call_id| tool_messages.fetch(tool_call_id, []) }
+            ([assistant] + messages).uniq.sort_by { |item| [item.sequence || 0, item.candidate_id] }
+          end
+
+          def canonical_tool_call_ids(candidate)
+            Array(candidate.metadata["tool_call_ids"] || candidate.metadata[:tool_call_ids])
+              .compact
+              .map(&:to_s)
+          end
+
+          def legacy_runtime_tool_exchange?(candidate, calls_by_llm)
+            candidate.llm_call_id &&
+              calls_by_llm.key?(candidate.llm_call_id) &&
+              %i[llm_message tool_call].include?(candidate.category)
+          end
+
+          def legacy_runtime_tool_exchange(candidate, assistant_by_llm:, calls_by_llm:, tool_results:)
+            llm_call_id = candidate.llm_call_id
+            calls = calls_by_llm.fetch(llm_call_id)
+            call_ids = calls.map(&:tool_call_id).compact
+            assistant = assistant_by_llm.fetch(llm_call_id, [])
+            results = call_ids.flat_map { |id| tool_results.fetch(id, []) }
+            (assistant + results).uniq.sort_by { |item| [item.sequence || 0, item.candidate_id] }
+          end
+
+          def legacy_import_tool_exchange(ordered, index, tool_results)
+            candidate = ordered.fetch(index)
+            return unless %i[llm_message tool_call].include?(candidate.category)
+            return if candidate.llm_call_id
+
+            group = []
+            cursor = index
+            if candidate.category == :llm_message
+              next_candidate = ordered[cursor + 1]
+              return unless next_candidate &&
+                next_candidate.category == :tool_call &&
+                contiguous_source?(candidate, next_candidate) &&
+                next_candidate.llm_call_id.nil?
+              group << candidate
+              cursor += 1
+            end
+
+            calls = []
+            while (item = ordered[cursor]) && item.category == :tool_call && item.llm_call_id.nil?
+              if calls.any? && !contiguous_source?(calls.last, item)
+                break
+              end
+              if group.any? && calls.empty? && !contiguous_source?(group.last, item)
+                break
+              end
+              calls << item
+              cursor += 1
+            end
+            return if calls.empty?
+
+            call_ids = calls.map(&:tool_call_id).compact
+            results = call_ids.flat_map { |id| tool_results.fetch(id, []) }
+            (group + calls + results).uniq.sort_by { |item| [item.sequence || 0, item.candidate_id] }
+          end
+
+          def contiguous_source?(left, right)
+            left_source = left.metadata["source_sequence"]
+            right_source = right.metadata["source_sequence"]
+            if left_source && right_source
+              Integer(right_source) == Integer(left_source) + 1
+            else
+              Integer(right.sequence) == Integer(left.sequence) + 1
+            end
+          end
+
+          def build_unit(candidates, kind:)
+            ids = candidates.map(&:candidate_id)
+            sequences = candidates.map(&:sequence).compact
+            requirements = candidates.map(&:requirement)
+            requirement = if requirements.include?(:protocol_required)
+              :protocol_required
+            elsif requirements.include?(:declared_required)
+              :declared_required
+            else
+              :optional
+            end
+            tool_call_ids = candidates.flat_map do |candidate|
+              call_ids = canonical_tool_call_ids(candidate)
+              call_ids << candidate.tool_call_id if candidate.tool_call_id
+              call_ids
+            end.compact.uniq
+            llm_call_ids = candidates.map(&:llm_call_id).compact.uniq
+            digest = Digest::SHA256.hexdigest(ids.join("\0"))[0, 20]
+
+            ContextSelectionUnit.new(
+              unit_id: "#{kind}:#{digest}",
+              candidate_ids: ids,
+              dependency_unit_ids: [],
+              kind: kind,
+              requirement: requirement,
+              priority: candidates.map(&:priority).max || 0,
+              sequence_range: [sequences.min || 0, sequences.max || 0],
+              metadata: {
+                "tool_call_ids" => tool_call_ids,
+                "llm_call_ids" => llm_call_ids
+              }
+            )
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,37 @@
+# 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_plan.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    ContextPlan = Data.define(
+      :selected_unit_ids,
+      :derived_contents,
+      :selected_tool_ids,
+      :ordering_hints,
+      :policy_descriptor,
+      :metadata
+    ) do
+      def initialize(**values)
+        super(**values.merge(
+          selected_unit_ids: Array(values[:selected_unit_ids]).map(&:to_s).freeze,
+          derived_contents: Array(values[:derived_contents]).freeze,
+          selected_tool_ids: Array(values[:selected_tool_ids]).map(&:to_s).freeze,
+          ordering_hints: Immutable.copy(values[:ordering_hints] || {}),
+          metadata: Immutable.copy(values[:metadata] || {})
+        ))
+        freeze
+      end
+    end
+  end
+end