phronomy 0.15.1 → 0.17.0

data/lib/phronomy/agent/immutable.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    module Immutable
+      module_function
+
+      def copy(value)
+        case value
+        when Hash
+          value.each_with_object({}) do |(key, child), result|
+            result[copy(key)] = copy(child)
+          end.freeze
+        when Array
+          value.map { |child| copy(child) }.freeze
+        when String
+          value.dup.freeze
+        else
+          value
+        end
+      end
+
+      def validate_canonical_json!(value, label: "value")
+        Phronomy::CanonicalJSON.dump(value)
+        true
+      rescue ArgumentError => error
+        raise ArgumentError, "#{label} is not canonical JSON compatible: #{error.message}"
+      end
+    end
+  end
+end

data/lib/phronomy/agent/journal_projection.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    class JournalProjection
+      MESSAGE_KINDS = %i[
+        external_message
+        assistant_message
+        tool_message
+      ].freeze
+      KNOWLEDGE_RESET_KINDS = %i[knowledge_cleared context_reset].freeze
+
+      def initialize(persistence:, agent_root:)
+        @persistence = persistence
+        @agent_root = agent_root
+      end
+
+      def transcript_records
+        generation = @agent_root.transcript_generation
+        records.select do |record|
+          record.context_candidate &&
+            record.context_generation == generation &&
+            MESSAGE_KINDS.include?(record.kind)
+        end
+      end
+
+      # Returns all persistent records eligible for Context selection.
+      # Knowledge has an independent logical lifetime from the transcript:
+      # clear_transcript! does not remove Knowledge, while knowledge_cleared and
+      # context_reset invalidate earlier Knowledge records by Journal position.
+      def context_records
+        (transcript_records + active_knowledge_records)
+          .sort_by { |record| [record.sequence || 0, record.record_id] }
+          .freeze
+      end
+
+      def llm_call_records
+        records.select { |record| record.kind == :llm_call_recorded }
+      end
+
+      def records
+        @records ||= @persistence.journals.read(@agent_root.agent_id)
+      end
+
+      private
+
+      def active_knowledge_records
+        reset_sequence = records.filter_map do |record|
+          record.sequence if KNOWLEDGE_RESET_KINDS.include?(record.kind)
+        end.max.to_i
+
+        records.select do |record|
+          record.context_candidate &&
+            record.kind == :knowledge &&
+            record.sequence.to_i > reset_sequence
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/agent/journal_record.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "time"
+
+module Phronomy
+  module Agent
+    # One immutable entry in the Agent's append-only Canonical Complete Execution Log.
+    #
+    # Raw logical execution facts are never rewritten for Context selection or
+    # compaction. Derived Context artifacts must be appended separately and keep
+    # stable provenance back to their raw source records.
+    class JournalRecord
+      ATTRIBUTES = %i[
+        record_id agent_id sequence execution_id llm_call_id kind channel role content_ref
+        parent_id causation_id correlation_id visibility context_generation
+        context_candidate occurred_at metadata
+      ].freeze
+
+      attr_reader(*ATTRIBUTES)
+
+      def initialize(
+        agent_id:,
+        kind:,
+        channel:,
+        record_id: SecureRandom.uuid,
+        sequence: nil,
+        execution_id: nil,
+        llm_call_id: nil,
+        role: nil,
+        content_ref: nil,
+        parent_id: nil,
+        causation_id: nil,
+        correlation_id: nil,
+        visibility: :agent,
+        context_generation: 0,
+        context_candidate: false,
+        occurred_at: Time.now.utc.iso8601(6),
+        metadata: {}
+      )
+        values = binding.local_variables.to_h { |name| [name, binding.local_variable_get(name)] }
+        ATTRIBUTES.each do |name|
+          value = values.fetch(name)
+          value = value.to_sym if %i[kind channel role visibility].include?(name) && value
+          instance_variable_set("@#{name}", Immutable.copy(value))
+        end
+        Immutable.validate_canonical_json!(metadata, label: "Journal metadata")
+        freeze
+      end
+
+      def with_sequence(sequence)
+        self.class.from_h(to_h.merge("sequence" => sequence))
+      end
+
+      def to_h
+        ATTRIBUTES.to_h { |name| [name.to_s, public_send(name)] }
+      end
+
+      def self.from_h(hash)
+        new(**ATTRIBUTES.to_h do |name|
+          key = hash.key?(name.to_s) ? name.to_s : name
+          [name, hash[key]]
+        end)
+      end
+    end
+  end
+end

data/lib/phronomy/agent/llm_call_record.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "time"
+
+module Phronomy
+  module Agent
+    class LLMCallRecord
+      STATUSES = %i[completed failed cancelled].freeze
+
+      ATTRIBUTES = %i[
+        llm_call_id execution_id sequence status manifest_ref output_ref
+        error_ref usage_ref started_at completed_at metadata
+      ].freeze
+      attr_reader(*ATTRIBUTES)
+
+      def initialize(
+        execution_id:,
+        sequence:,
+        status:,
+        manifest_ref:,
+        llm_call_id: SecureRandom.uuid,
+        output_ref: nil,
+        error_ref: nil,
+        usage_ref: nil,
+        started_at: Time.now.utc.iso8601(6),
+        completed_at: nil,
+        metadata: {}
+      )
+        values = binding.local_variables.to_h { |name| [name, binding.local_variable_get(name)] }
+        ATTRIBUTES.each do |name|
+          value = values.fetch(name)
+          value = value.to_sym if name == :status
+          instance_variable_set("@#{name}", Immutable.copy(value))
+        end
+        raise ArgumentError, "unknown LLM Call status: #{status.inspect}" unless STATUSES.include?(status)
+        raise ArgumentError, "LLM Call sequence must be positive" unless sequence.positive?
+        Immutable.validate_canonical_json!(metadata, label: "LLM Call metadata")
+        freeze
+      end
+
+      def to_h
+        ATTRIBUTES.to_h do |name|
+          value = public_send(name)
+          value = value.to_s if name == :status
+          [name.to_s, value]
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/agent/llm_input_build_context.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    # Immutable metadata passed to before_llm_input hooks. Runtime objects such
+    # as RubyLLM::Chat, messages and the mutable Agent instance are not exposed.
+    LLMInputBuildContext = Data.define(
+      :agent_id, :agent_definition_id, :definition_version,
+      :config, :call_sequence
+    ) do
+      def initialize(**values)
+        super(**values.merge(config: Immutable.copy(values.fetch(:config, {}))))
+        freeze
+      end
+    end
+  end
+end

data/lib/phronomy/agent/llm_input_manifest.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    class LLMInputManifest
+      VERSION = 1
+      CALL_MODES = %i[ask complete].freeze
+
+      Segment = Data.define(
+        :position, :category, :role, :content_ref, :delivery,
+        :tool_call_id, :metadata
+      ) do
+        def initialize(**values)
+          super(**values.merge(metadata: Immutable.copy(values[:metadata] || {})))
+          freeze
+        end
+
+        def to_h
+          {
+            "position" => position,
+            "category" => category.to_s,
+            "role" => role&.to_s,
+            "content_ref" => content_ref,
+            "delivery" => delivery.to_s,
+            "tool_call_id" => tool_call_id,
+            "metadata" => metadata
+          }.compact
+        end
+      end
+
+      attr_reader :version, :call_sequence, :call_mode,
+        :assembly_policy_version, :segments,
+        :model_config_ref, :tool_definitions_ref, :response_schema_ref,
+        :ruby_llm_version, :adapter_name, :adapter_version
+
+      def initialize(
+        call_sequence:,
+        call_mode:,
+        segments:,
+        model_config_ref:,
+        tool_definitions_ref: nil,
+        response_schema_ref: nil,
+        assembly_policy_version: 1,
+        ruby_llm_version: nil,
+        adapter_name: nil,
+        adapter_version: nil,
+        version: VERSION
+      )
+        @version = Integer(version)
+        @call_sequence = Integer(call_sequence)
+        @call_mode = call_mode.to_sym
+        @assembly_policy_version = Integer(assembly_policy_version)
+        @segments = Array(segments).sort_by(&:position).freeze
+        @model_config_ref = model_config_ref.to_s.freeze
+        @tool_definitions_ref = tool_definitions_ref&.to_s&.freeze
+        @response_schema_ref = response_schema_ref&.to_s&.freeze
+        @ruby_llm_version = ruby_llm_version&.to_s&.freeze
+        @adapter_name = adapter_name&.to_s&.freeze
+        @adapter_version = adapter_version&.to_s&.freeze
+        validate!
+        freeze
+      end
+
+      def referenced_content_refs
+        ([model_config_ref, tool_definitions_ref, response_schema_ref] +
+          segments.map(&:content_ref)).compact.uniq.freeze
+      end
+
+      def to_h
+        {
+          "version" => version,
+          "call_sequence" => call_sequence,
+          "call_mode" => call_mode.to_s,
+          "assembly_policy_version" => assembly_policy_version,
+          "segments" => segments.map(&:to_h),
+          "model_config_ref" => model_config_ref,
+          "tool_definitions_ref" => tool_definitions_ref,
+          "response_schema_ref" => response_schema_ref,
+          "ruby_llm_version" => ruby_llm_version,
+          "adapter_name" => adapter_name,
+          "adapter_version" => adapter_version
+        }.compact
+      end
+
+      private
+
+      def validate!
+        raise ArgumentError, "invalid manifest call mode: #{call_mode.inspect}" unless CALL_MODES.include?(call_mode)
+        raise ArgumentError, "call_sequence must be positive" unless call_sequence.positive?
+        expected = (0...segments.length).to_a
+        actual = segments.map(&:position)
+        raise ArgumentError, "manifest positions must be contiguous: #{actual.inspect}" unless actual == expected
+
+        ask_count = segments.count { |segment| segment.delivery == :ask_argument }
+        expected_ask_count = (call_mode == :ask) ? 1 : 0
+        unless ask_count == expected_ask_count
+          raise ArgumentError,
+            "#{call_mode} manifest requires #{expected_ask_count} ask_argument segment(s), got #{ask_count}"
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/agent/llm_input_patch.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    # Typed, canonicalizable input customization returned by before_llm_input.
+    # v1 deliberately exposes only fields that are fully applied to every call.
+    LLMInputPatch = Data.define(:model_config_patch, :segment_candidates) do
+      def initialize(model_config_patch: nil, segment_candidates: nil)
+        super(
+          model_config_patch: model_config_patch && Immutable.copy(model_config_patch),
+          segment_candidates: segment_candidates && Immutable.copy(Array(segment_candidates))
+        )
+        freeze
+      end
+
+      def self.empty
+        new
+      end
+    end
+  end
+end

data/lib/phronomy/agent/phase_machine_builder.rb

@@ -99,6 +99,18 @@ module Phronomy
               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(

data/lib/phronomy/agent/provider_call_outcome.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    # Immutable, Phronomy-owned snapshot of one completed Provider assistant output.
+    # It is captured before Agent-owned Tool execution begins, so durable logging
+    # never depends on RubyLLM's later control flow or Application callbacks.
+    ProviderCallOutcome = Data.define(:role, :content, :tool_calls, :usage, :metadata) do
+      def self.capture(message)
+        return if message.nil?
+
+        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.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
+          if value.respond_to?(:to_h)
+            normalize(value.to_h)
+          else
+            value.to_s
+          end
+        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 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/ruby_llm_materializer.rb

@@ -0,0 +1,189 @@
+# 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)
+        segments.map { |segment| materialize_segment(segment) }
+      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_result
+          raise ArgumentError, "raw Tool result is not an LLM message"
+        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
+    end
+  end
+end