phronomy 0.15.0 → 0.16.0

data/lib/phronomy/agent/fsm_runtime_adapter.rb

@@ -0,0 +1,210 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    # Adapts the current AgentInvocation FSM to the ideal manifest-first model.
+    # Every LLM Call receives a freshly fixed Manifest. Persistence and
+    # projection preparation run on BlockingAdapterPool, never on EventLoop.
+    module FsmRuntimeAdapter
+      private
+
+      def filtering_input_action(_agent, invocation)
+        invocation.input = invocation.config.fetch(:phronomy_filtered_input)
+        invocation
+      end
+
+      def building_context_action(agent, invocation)
+        projection = invocation.config.fetch(:phronomy_runtime_projection)
+        invocation.chat = agent.send(:build_chat, model_config: projection.model_config)
+        agent.send(
+          :_apply_context_to_chat,
+          invocation.chat,
+          {
+            system: projection.system,
+            messages: projection.messages,
+            tool_classes: projection.tool_classes,
+            model_config: projection.model_config
+          }
+        )
+        install_tool_interceptors(invocation.chat, invocation)
+        invocation
+      end
+
+      def calling_llm_action(agent, runtime, invocation)
+        prepare_and_start_llm_call(
+          agent,
+          runtime,
+          invocation,
+          streaming: false
+        )
+        invocation
+      end
+
+      def calling_llm_stream_action(agent, runtime, invocation)
+        prepare_and_start_llm_call(
+          agent,
+          runtime,
+          invocation,
+          streaming: true
+        )
+        invocation
+      end
+
+      def prepare_and_start_llm_call(agent, runtime, invocation, streaming:)
+        activation = invocation.config.fetch(:phronomy_activation)
+        if invocation.user_message_sent
+          preparation = runtime.blocking_io.submit do
+            activation.coordinator.prepare_next_llm_call(activation)
+          end
+          preparation.on_complete do |projection, error|
+            if error
+              post_preparation_failure(runtime, invocation, error, streaming: streaming)
+            else
+              start_provider_call(
+                agent,
+                runtime,
+                invocation,
+                activation,
+                projection,
+                streaming: streaming,
+                replace_messages: true
+              )
+            end
+          end
+        else
+          start_provider_call(
+            agent,
+            runtime,
+            invocation,
+            activation,
+            activation.runtime_projection,
+            streaming: streaming,
+            replace_messages: false
+          )
+        end
+      end
+
+      def start_provider_call(
+        agent,
+        runtime,
+        invocation,
+        activation,
+        projection,
+        streaming:,
+        replace_messages:
+      )
+        call_started = false
+        agent.send(
+          :check_cancellation!,
+          invocation.config,
+          "invocation cancelled before LLM call"
+        )
+        if replace_messages
+          invocation.chat = agent.send(:build_chat, model_config: projection.model_config)
+          agent.send(
+            :_apply_context_to_chat,
+            invocation.chat,
+            {
+              system: projection.system,
+              messages: projection.messages,
+              tool_classes: projection.tool_classes,
+              model_config: projection.model_config
+            }
+          )
+          install_tool_interceptors(invocation.chat, invocation)
+          invocation.config[:phronomy_runtime_projection] = projection
+        end
+
+        call_context = activation.begin_llm_call(projection)
+        call_started = true
+        invocation.begin_llm_call!(call_context.fetch(:llm_call_id))
+        message = projection.ask_message
+
+        operation = if streaming
+          Phronomy.configuration.llm_adapter.stream_async(
+            invocation.chat,
+            message,
+            config: invocation.config
+          ) do |chunk|
+            agent.send(
+              :check_cancellation!,
+              invocation.config,
+              "invocation cancelled during streaming"
+            )
+            post_to_invocation!(
+              runtime,
+              invocation.id,
+              :llm_stream_chunk,
+              {content: chunk.content}
+            )
+          end
+        else
+          Phronomy.configuration.llm_adapter.complete_async(
+            invocation.chat,
+            message,
+            config: invocation.config
+          )
+        end
+        observe_manifest_call(
+          operation,
+          activation,
+          invocation,
+          runtime: runtime,
+          streaming: streaming
+        )
+      rescue => error
+        if call_started
+          activation.record_llm_result(
+            response: canonical_response_for(nil, error),
+            error: error,
+            streaming: streaming
+          )
+        end
+        post_llm_result(runtime, invocation, nil, error, streaming: streaming)
+      end
+
+      def observe_manifest_call(operation, activation, invocation, runtime:, streaming:)
+        operation.on_complete do |response, error|
+          activation.record_llm_result(
+            response: canonical_response_for(response, error),
+            error: error,
+            streaming: streaming
+          )
+          post_llm_result(
+            runtime,
+            invocation,
+            response,
+            error,
+            streaming: streaming
+          )
+        end
+      end
+
+      def canonical_response_for(response, error)
+        if error.is_a?(ToolCallIntercepted)
+          error.assistant_outcome || ProviderCallOutcome.capture(response)
+        else
+          ProviderCallOutcome.capture(response)
+        end
+      end
+
+      def post_preparation_failure(runtime, invocation, error, streaming:)
+        post_llm_result(runtime, invocation, nil, error, streaming: streaming)
+      end
+
+      def post_llm_result(runtime, invocation, response, error, streaming:)
+        result = LLMOperationResult.new(
+          response: response,
+          error: error,
+          streaming: streaming
+        )
+        event_type = if error && !error.is_a?(ToolCallIntercepted)
+          :llm_failed
+        else
+          :llm_completed
+        end
+        post_to_invocation!(runtime, invocation.id, event_type, result)
+      end
+    end
+  end
+end

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,34 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    class JournalProjection
+      MESSAGE_KINDS = %i[
+        external_message assistant_message tool_message
+        llm_message tool_call tool_result
+      ].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
+
+      def llm_call_records
+        records.select { |record| record.kind == :llm_call_recorded }
+      end
+
+      def records
+        @records ||= @persistence.journals.read(@agent_root.agent_id)
+      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