phronomy 0.15.0 → 0.16.0

data/lib/phronomy/agent/ruby_llm_materializer.rb

@@ -0,0 +1,298 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    class RubyLLMMaterializer
+      RuntimeProjection = Data.define(
+        :system, :messages, :tool_classes, :ask_message,
+        :model_config, :manifest, :manifest_ref
+      )
+
+      def initialize(agent:, persistence:)
+        @agent = agent
+        @persistence = persistence
+      end
+
+      def materialize(manifest:, manifest_ref:)
+        verify_manifest_identity!(manifest, manifest_ref)
+        verify_adapter!(manifest)
+        tool_set = verify_tool_definitions!(manifest)
+        model_config = fetch_json(manifest.model_config_ref)
+        system_parts = []
+        message_segments = []
+        ask_message = nil
+
+        manifest.segments.each do |segment|
+          case segment.delivery
+          when :ask_argument
+            ask_message = @persistence.contents.fetch_text(segment.content_ref)
+          when :chat_message
+            if segment.role == :system
+              system_parts << @persistence.contents.fetch_text(segment.content_ref)
+            else
+              message_segments << segment
+            end
+          else
+            raise ArgumentError, "unknown manifest delivery: #{segment.delivery.inspect}"
+          end
+        end
+
+        RuntimeProjection.new(
+          system: system_parts.empty? ? nil : system_parts.join("\n\n"),
+          messages: materialize_message_segments(message_segments).freeze,
+          tool_classes: tool_set.runtime_tools,
+          ask_message: ask_message,
+          model_config: Immutable.copy(model_config),
+          manifest: manifest,
+          manifest_ref: manifest_ref
+        )
+      end
+
+      def materialize_journal_record(record)
+        materialize_segment(segment_from_record(record))
+      end
+
+      def materialize_journal_records(records)
+        segments = Array(records).each_with_index.map do |record, index|
+          segment_from_record(record, position: index)
+        end
+        materialize_message_segments(segments).freeze
+      end
+
+      private
+
+      def segment_from_record(record, position: 0)
+        LLMInputManifest::Segment.new(
+          position: position,
+          category: record.kind,
+          role: record.role,
+          content_ref: record.content_ref,
+          delivery: :chat_message,
+          tool_call_id: record.metadata["tool_call_id"] || record.metadata[:tool_call_id],
+          metadata: record.metadata.merge(
+            "journal_record_id" => record.record_id,
+            "journal_sequence" => record.sequence,
+            "llm_call_id" => record.llm_call_id
+          ).compact
+        )
+      end
+
+      def verify_manifest_identity!(manifest, manifest_ref)
+        expected = @persistence.contents.fetch(manifest_ref)
+        actual = Phronomy::CanonicalJSON.dump(manifest.to_h)
+        return if expected == actual
+
+        raise Phronomy::ContentStore::IntegrityError,
+          "manifest content does not match manifest_ref: #{manifest_ref}"
+      end
+
+      def verify_adapter!(manifest)
+        actual = Phronomy.configuration.llm_adapter.class.name
+        return if manifest.adapter_name.nil? || manifest.adapter_name == actual
+
+        raise Phronomy::ConfigurationError,
+          "LLM adapter changed after manifest creation: #{manifest.adapter_name} -> #{actual}"
+      end
+
+      def verify_tool_definitions!(manifest)
+        tool_set = ToolDefinitionSet.build(@agent)
+        return tool_set unless manifest.tool_definitions_ref
+
+        expected = @persistence.contents.fetch(manifest.tool_definitions_ref)
+        actual = Phronomy::CanonicalJSON.dump(tool_set.definitions)
+        unless expected == actual
+          raise Phronomy::ConfigurationError,
+            "Agent tool definitions changed after manifest creation"
+        end
+        tool_set
+      end
+
+      def fetch_json(content_ref)
+        Phronomy::CanonicalJSON.load(@persistence.contents.fetch(content_ref))
+      end
+
+      def materialize_message_segments(segments)
+        result = []
+        index = 0
+        while index < segments.length
+          segment = segments[index]
+          if legacy_assistant_segment?(segment)
+            grouped, consumed = legacy_assistant_group(segments, index)
+            result << materialize_legacy_assistant_group(grouped)
+            index += consumed
+          else
+            result << materialize_segment(segment)
+            index += 1
+          end
+        end
+        result
+      end
+
+      # New canonical records preserve one logical assistant/tool message per
+      # record. These legacy helpers remain only so already-persisted state from
+      # the preceding stateful refactor can still be read during migration.
+      def legacy_assistant_segment?(segment)
+        segment.role&.to_sym == :assistant &&
+          %i[llm_message tool_call].include?(segment.category.to_sym)
+      end
+
+      def legacy_assistant_group(segments, start_index)
+        first = segments.fetch(start_index)
+        llm_call_id = metadata_value(first, "llm_call_id")
+        return legacy_runtime_assistant_group(segments, start_index, llm_call_id) if llm_call_id
+
+        legacy_import_assistant_group(segments, start_index)
+      end
+
+      def legacy_runtime_assistant_group(segments, start_index, llm_call_id)
+        group = []
+        index = start_index
+        while (segment = segments[index]) && legacy_assistant_segment?(segment) &&
+            metadata_value(segment, "llm_call_id").to_s == llm_call_id.to_s
+          group << segment
+          index += 1
+        end
+        [group, group.length]
+      end
+
+      def legacy_import_assistant_group(segments, start_index)
+        first = segments.fetch(start_index)
+        group = [first]
+        index = start_index + 1
+        last = first
+
+        while (segment = segments[index]) && legacy_assistant_segment?(segment)
+          break unless segment.category.to_sym == :tool_call
+          break unless contiguous_source?(last, segment)
+          break if metadata_value(segment, "llm_call_id")
+
+          group << segment
+          last = segment
+          index += 1
+        end
+        [group, group.length]
+      end
+
+      def contiguous_source?(left, right)
+        left_sequence = metadata_value(left, "journal_sequence")
+        right_sequence = metadata_value(right, "journal_sequence")
+        return false unless left_sequence && right_sequence
+
+        Integer(right_sequence) == Integer(left_sequence) + 1
+      end
+
+      def materialize_legacy_assistant_group(segments)
+        content_segments = segments.select { |segment| segment.category.to_sym == :llm_message }
+        if content_segments.length > 1
+          raise ArgumentError, "ambiguous assistant message group contains multiple content records"
+        end
+
+        tool_calls = {}
+        segments.select { |segment| segment.category.to_sym == :tool_call }.each do |segment|
+          payload = fetch_json(segment.content_ref)
+          tool_call_id = payload.fetch("id").to_s
+          if tool_calls.key?(tool_call_id)
+            raise ArgumentError, "duplicate Tool Call in assistant message: #{tool_call_id}"
+          end
+          tool_calls[tool_call_id] = materialize_tool_call(payload)
+        end
+
+        content = if content_segments.empty?
+          ""
+        else
+          @persistence.contents.fetch_text(content_segments.first.content_ref)
+        end
+
+        RubyLLM::Message.new(
+          role: :assistant,
+          content: content,
+          tool_calls: tool_calls.empty? ? nil : tool_calls
+        )
+      end
+
+      def materialize_segment(segment)
+        case segment.category.to_sym
+        when :assistant_message
+          materialize_canonical_message(segment, expected_role: :assistant)
+        when :tool_message
+          materialize_canonical_message(segment, expected_role: :tool)
+        when :tool_call
+          materialize_legacy_assistant_group([segment])
+        when :tool_result
+          unless segment.role&.to_sym == :tool
+            raise ArgumentError, "raw Tool result is not an LLM message"
+          end
+          RubyLLM::Message.new(
+            role: :tool,
+            content: @persistence.contents.fetch_text(segment.content_ref),
+            tool_call_id: segment.tool_call_id ||
+              segment.metadata["tool_call_id"] || segment.metadata[:tool_call_id]
+          )
+        else
+          RubyLLM::Message.new(
+            role: segment.role,
+            content: @persistence.contents.fetch_text(segment.content_ref),
+            tool_call_id: segment.tool_call_id
+          )
+        end
+      end
+
+      def materialize_canonical_message(segment, expected_role:)
+        payload = fetch_json(segment.content_ref)
+        role = payload.fetch("role").to_sym
+        unless role == expected_role
+          raise ArgumentError,
+            "canonical #{segment.category} role mismatch: #{role.inspect}"
+        end
+        if segment.role && segment.role.to_sym != role
+          raise ArgumentError,
+            "manifest role does not match canonical message: #{segment.role.inspect} != #{role.inspect}"
+        end
+
+        tool_calls = materialize_tool_calls(payload["tool_calls"])
+        message = RubyLLM::Message.new(
+          role: role,
+          content: initial_content_for(role, payload.fetch("content", nil), tool_calls),
+          tool_calls: tool_calls.empty? ? nil : tool_calls,
+          tool_call_id: payload["tool_call_id"],
+          model_id: payload["model_id"]
+        )
+
+        # RubyLLM normalizes Hash content during Message initialization. A
+        # canonical message may legitimately contain structured assistant
+        # content, so restore the captured logical value after construction.
+        message.content = payload["content"] if payload.key?("content")
+        message
+      end
+
+      def initial_content_for(role, content, tool_calls)
+        return "" if role == :assistant && content.nil? && !tool_calls.empty?
+
+        content.nil? ? "" : content
+      end
+
+      def materialize_tool_calls(payloads)
+        Array(payloads).each_with_object({}) do |payload, result|
+          tool_call_id = payload.fetch("id").to_s
+          if result.key?(tool_call_id)
+            raise ArgumentError, "duplicate Tool Call in assistant message: #{tool_call_id}"
+          end
+          result[tool_call_id] = materialize_tool_call(payload)
+        end
+      end
+
+      def materialize_tool_call(payload)
+        RubyLLM::ToolCall.new(
+          id: payload.fetch("id").to_s,
+          name: payload.fetch("name"),
+          arguments: payload.fetch("arguments", {}),
+          thought_signature: payload["thought_signature"]
+        )
+      end
+
+      def metadata_value(segment, name)
+        segment.metadata[name] || segment.metadata[name.to_sym]
+      end
+    end
+  end
+end

data/lib/phronomy/agent/token_budget_resolver.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    # Resolves a TokenBudget from the effective model configuration that will
+    # actually be materialized for one LLM call.
+    class TokenBudgetResolver
+      def initialize(agent:)
+        @agent = agent
+      end
+
+      def resolve(model_config)
+        config = stringify_keys(model_config)
+        model_name = config["model"]
+        explicit_window = integer_or_nil(config["context_window"])
+        explicit_reserve = integer_or_nil(config["max_output_tokens"])
+
+        if explicit_window
+          reserve = explicit_reserve || configured_default_reserve
+          return build_budget(explicit_window, reserve, model_name)
+        end
+
+        return nil unless model_name
+
+        model = RubyLLM.models.find(model_name)
+        return nil unless model
+
+        context_window = model.context_window.to_i
+        registry_max = model.max_output_tokens.to_i
+        reserve = explicit_reserve || configured_default_reserve
+        reserve ||= registry_max if registry_max.positive? && registry_max < context_window
+        build_budget(context_window, reserve, model_name)
+      rescue RubyLLM::ModelNotFoundError
+        nil
+      end
+
+      private
+
+      def build_budget(context_window, reserve, model_name)
+        unless reserve&.positive? && reserve < context_window
+          raise Phronomy::InvalidContextBudgetConfigurationError,
+            "Cannot determine a valid output reserve for model #{model_name.inspect}; " \
+            "set max_output_tokens or Phronomy.configuration.default_output_reserve"
+        end
+
+        # ContextAssembler passes the actual mandatory Manifest content to
+        # ContextSelector. Reserving context_overhead here would count system
+        # instructions and tool definitions a second time.
+        Phronomy::LlmContextWindow::TokenBudget.new(
+          context_window: context_window,
+          max_output_tokens: reserve
+        )
+      end
+
+      def configured_default_reserve
+        integer_or_nil(Phronomy.configuration.default_output_reserve)
+      end
+
+      def integer_or_nil(value)
+        return nil if value.nil?
+        Integer(value)
+      end
+
+      def stringify_keys(hash)
+        hash.to_h.each_with_object({}) { |(key, value), result| result[key.to_s] = value }
+      end
+    end
+  end
+end

data/lib/phronomy/agent/tool_call_intercepted.rb

@@ -2,18 +2,25 @@
 
 module Phronomy
   module Agent
-    # Raised by the Agent-owned RubyLLM ToolCall interceptor before execution.
+    # Normal control-transfer signal raised before RubyLLM executes a Tool Call.
+    #
+    # RubyLLM >= 1.15 guarantees that the complete assistant message has already
+    # been added to Chat#messages before before_tool_call 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
+      attr_reader :tool_calls, :assistant_message, :assistant_outcome, :llm_call_id
 
-      def initialize(tool_calls)
+      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
 
-      # Convenience accessor for callers that only support one ToolCall.
       def tool_call
         @tool_calls.first
       end

data/lib/phronomy/agent/tool_definition_set.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    class ToolDefinitionSet
+      attr_reader :runtime_tools, :definitions
+
+      def self.build(agent)
+        runtime_tools = (agent.class.tools + agent.send(:_handoff_tools)).freeze
+        definitions = runtime_tools.map do |tool_class|
+          prepared = agent.send(:prepare_tool_class, tool_class)
+          tool = prepared.is_a?(Class) ? prepared.new : prepared
+          {
+            "name" => tool.name.to_s,
+            "description" => tool.description.to_s,
+            "parameters_schema" => normalize(
+              tool.respond_to?(:parameters_schema) ? tool.parameters_schema : {}
+            ),
+            "provider_options" => normalize(
+              tool.respond_to?(:provider_options) ? tool.provider_options : {}
+            )
+          }
+        end.freeze
+        new(runtime_tools: runtime_tools, definitions: definitions)
+      end
+
+      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
+          if value.respond_to?(:to_json_schema)
+            normalize(value.to_json_schema)
+          elsif value.respond_to?(:to_h)
+            normalize(value.to_h)
+          else
+            raise ArgumentError, "unsupported tool definition value: #{value.class}"
+          end
+        end
+      end
+
+      def initialize(runtime_tools:, definitions:)
+        @runtime_tools = runtime_tools
+        @definitions = Immutable.copy(definitions)
+        freeze
+      end
+    end
+  end
+end

data/lib/phronomy/agent.rb

@@ -2,28 +2,26 @@
 
 module Phronomy
   module Agent
-    # Immutable event emitted by Agent async APIs.
-    #
-    # invoke_async and stream_async share lifecycle and Tool events. Streaming
-    # additionally emits :token events.
-    #
-    # Common event types:
-    #   :tool_call
-    #   :tool_result
-    #   :approval_required
-    #   :done
-    #   :error
-    #   :timeout
-    #   :cancelled
-    #
-    # Streaming-only event type:
-    #   :token
     StreamEvent = Data.define(:type, :payload)
+
+    def self.run_once(definition:, input:, context: nil, **invoke_options)
+      persistence = Phronomy::Persistence::InMemory.new
+      agent = definition.create(context: context, persistence: persistence)
+      agent.invoke(input, **invoke_options)
+    end
   end
 end
 
+require_relative "agent/fsm_runtime_adapter"
 require_relative "agent/async_event_api"
 
+unless Phronomy::Agent::AgentInvocationSessionBuilder.singleton_class <
+    Phronomy::Agent::FsmRuntimeAdapter
+  Phronomy::Agent::AgentInvocationSessionBuilder.singleton_class.prepend(
+    Phronomy::Agent::FsmRuntimeAdapter
+  )
+end
+
 unless Phronomy::Agent::Base < Phronomy::Agent::AsyncEventApi
   Phronomy::Agent::Base.prepend(Phronomy::Agent::AsyncEventApi)
 end

data/lib/phronomy/agent_busy_error.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Phronomy
+  class AgentBusyError < Phronomy::Error; end
+end

data/lib/phronomy/canonical_json.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Phronomy
+  # Phronomy Canonical JSON v1.
+  #
+  # v1 accepts JSON-native values only, orders object names by UTF-16 code
+  # units, and emits ECMAScript/JCS-compatible number forms for IEEE-754
+  # doubles. Ruby-specific and non-interoperable numeric values must be
+  # converted by a domain codec before serialization.
+  class CanonicalJSON
+    VERSION = 1
+    MAX_SAFE_INTEGER = 9_007_199_254_740_991
+
+    class << self
+      def dump(value)
+        serialize(value)
+      end
+
+      def load(bytes)
+        JSON.parse(bytes)
+      end
+
+      private
+
+      def serialize(value)
+        case value
+        when Hash
+          serialize_hash(value)
+        when Array
+          "[#{value.map { |child| serialize(child) }.join(",")}]"
+        when String
+          JSON.generate(ensure_utf8(value))
+        when Integer
+          serialize_integer(value)
+        when Float
+          serialize_float(value)
+        when TrueClass then "true"
+        when FalseClass then "false"
+        when NilClass then "null"
+        else
+          raise ArgumentError,
+            "unsupported Phronomy Canonical JSON v1 value: #{value.class}"
+        end
+      end
+
+      def serialize_hash(value)
+        normalized = {}
+        value.each do |key, child|
+          unless key.is_a?(String)
+            raise ArgumentError,
+              "canonical JSON object keys must be String, got #{key.class}"
+          end
+          canonical_key = ensure_utf8(key)
+          if normalized.key?(canonical_key)
+            raise ArgumentError,
+              "duplicate canonical JSON key: #{canonical_key.inspect}"
+          end
+          normalized[canonical_key] = child
+        end
+
+        members = normalized.sort_by { |key, _| utf16_sort_key(key) }.map do |key, child|
+          "#{JSON.generate(key)}:#{serialize(child)}"
+        end
+        "{#{members.join(",")}}"
+      end
+
+      def serialize_integer(value)
+        if value.abs > MAX_SAFE_INTEGER
+          raise ArgumentError,
+            "integer exceeds canonical JSON safe range; encode it as a String: #{value}"
+        end
+        value.to_s
+      end
+
+      def serialize_float(value)
+        raise ArgumentError, "non-finite number is not canonical JSON" unless value.finite?
+        raise ArgumentError, "-0.0 is not canonical JSON v1" if negative_zero?(value)
+        return "0" if value.zero?
+
+        raw = value.to_s.downcase
+        return normalize_plain_decimal(raw) unless raw.include?("e")
+
+        sign = raw.start_with?("-") ? "-" : ""
+        raw = raw.delete_prefix("-")
+        mantissa, exponent_text = raw.split("e", 2)
+        exponent = Integer(exponent_text, 10)
+        integer_part, fractional_part = mantissa.split(".", 2)
+        fractional_part ||= ""
+        digits = (integer_part + fractional_part).sub(/0+\z/, "")
+        digits = "0" if digits.empty?
+        decimal_position = integer_part.length + exponent
+
+        body = if decimal_position > 0 && decimal_position <= 21
+          if decimal_position >= digits.length
+            digits + ("0" * (decimal_position - digits.length))
+          else
+            "#{digits[0, decimal_position]}.#{digits[decimal_position..]}"
+          end
+        elsif decimal_position <= 0 && decimal_position > -6
+          "0.#{"0" * -decimal_position}#{digits}"
+        else
+          scientific_exponent = decimal_position - 1
+          fraction = digits[1..]
+          coefficient = (fraction.nil? || fraction.empty?) ? digits[0] : "#{digits[0]}.#{fraction}"
+          exponent_sign = scientific_exponent.negative? ? "" : "+"
+          "#{coefficient}e#{exponent_sign}#{scientific_exponent}"
+        end
+        "#{sign}#{body}"
+      end
+
+      def normalize_plain_decimal(raw)
+        raw = raw.delete_suffix(".0")
+        (raw == "-0") ? "0" : raw
+      end
+
+      def negative_zero?(value)
+        value.zero? && (1.0 / value).negative?
+      end
+
+      def utf16_sort_key(value)
+        value.encode(Encoding::UTF_16BE).bytes
+      end
+
+      def ensure_utf8(value)
+        text = value.dup.encode(Encoding::UTF_8)
+        raise ArgumentError, "invalid UTF-8 string" unless text.valid_encoding?
+
+        text
+      rescue EncodingError => error
+        raise ArgumentError, "invalid UTF-8 string: #{error.message}"
+      end
+    end
+  end
+end

data/lib/phronomy/configuration.rb

@@ -22,11 +22,16 @@ module Phronomy
     # Tracer instance
     attr_accessor :tracer
 
-    # Global before_completion hook callable (Proc / lambda).
+    # Global before_llm_input hook callable (Proc / lambda).
     # Called before every LLM request across all agents.
-    # Receives a {Phronomy::Agent::BeforeCompletionContext}; must return a Hash
-    # of params to merge, or nil to pass through unchanged.
-    attr_accessor :before_completion
+    # Receives a {Phronomy::Agent::LLMInputBuildContext}; must return a
+    # {Phronomy::Agent::LLMInputPatch} or nil to pass through unchanged.
+    attr_accessor :before_llm_input
+
+    # Default output token reservation when an agent does not set max_output_tokens
+    # and the model registry value equals the context window (making it unusable
+    # as a per-request output reserve). Integer or nil.
+    attr_accessor :default_output_reserve
 
     # Recursion limit for graph execution (default: 25)
     attr_accessor :recursion_limit