phronomy 0.15.1 → 0.17.0

data/lib/phronomy/agent/agent_invocation_session_builder.rb

@@ -6,6 +6,7 @@ module Phronomy
     #
     # Blocking/provider work returns through explicit Agent-internal events.
     # Entry actions start operations and return synchronously.
+    # Every LLM Call is prepared from a canonical Manifest and RuntimeProjection.
     #
     # @api private
     class AgentInvocationSessionBuilder
@@ -40,7 +41,6 @@ module Phronomy
       def self.build(
         agent:,
         input:,
-        messages:,
         config:,
         approval_policy: nil,
         approval_listener: nil,
@@ -51,7 +51,6 @@ module Phronomy
         invocation = AgentInvocation.new(
           agent: agent,
           input: input,
-          messages: messages,
           config: config,
           approval_policy: approval_policy,
           approval_listener: approval_listener,
@@ -132,6 +131,17 @@ module Phronomy
           ],
           resume: [
             {from: :suspended, to: :waiting_for_tools, guard: nil}
+          ],
+          application_callback_failed: [
+            {from: :filtering_input, to: :failed, guard: nil},
+            {from: :building_context, to: :failed, guard: nil},
+            {from: :calling_llm, to: :failed, guard: nil},
+            {from: :starting_tools, to: :failed, guard: nil},
+            {from: :evaluating_tools, to: :failed, guard: nil},
+            {from: :waiting_for_tools, to: :failed, guard: nil},
+            {from: :dispatching_tools, to: :failed, guard: nil},
+            {from: :recording_tool_results, to: :failed, guard: nil},
+            {from: :output_filtering, to: :failed, guard: nil}
           ]
         )
       end
@@ -170,84 +180,78 @@ module Phronomy
       end
       private_class_method :build_entry_actions
 
-      def self.filtering_input_action(agent, invocation)
-        agent.send(
-          :check_cancellation!,
-          invocation.config,
-          "invocation cancelled before input filtering"
-        )
-        invocation.input = agent.send(
-          :run_input_filters!,
-          invocation.input
-        )
-        invocation
-      rescue Phronomy::FilterBlockError => error
-        invocation.input_blocked = true
-        invocation.block_error = error
+      def self.filtering_input_action(_agent, invocation)
+        invocation.input = invocation.config.fetch(:phronomy_filtered_input)
         invocation
       end
       private_class_method :filtering_input_action
 
       def self.building_context_action(agent, invocation)
-        invocation.chat = agent.send(:build_chat)
-        context = agent.send(
-          :build_context,
-          invocation.input,
-          messages: invocation.messages,
-          thread_id: invocation.thread_id,
-          config: invocation.config,
-          budget: agent.send(:build_token_budget),
-          instruction: agent.send(:build_instructions, invocation.input),
-          tools: agent.class.tools + agent.send(:_handoff_tools)
-        )
-        agent.send(:_apply_context_to_chat, invocation.chat, context)
+        projection = invocation.config.fetch(:phronomy_runtime_projection)
+        invocation.chat = agent.send(:build_chat, model_config: projection.model_config)
         agent.send(
-          :run_before_completion_hooks!,
+          :_apply_runtime_projection_to_chat,
           invocation.chat,
-          invocation.config
+          projection,
+          invocation: invocation
         )
-        install_tool_interceptors(invocation.chat)
+        install_tool_interceptors(invocation.chat, invocation)
         invocation
       end
       private_class_method :building_context_action
 
-      def self.install_tool_interceptors(chat)
+      # RubyLLM >= 1.15 adds the complete assistant Message to chat.messages
+      # before before_tool_call is fired. Capture that Message at the control
+      # boundary instead of trying to recover it after the exception unwinds.
+      def self.install_tool_interceptors(chat, invocation = nil)
+        unless chat.respond_to?(:before_tool_call)
+          raise Phronomy::ConfigurationError,
+            "Agent-owned Tool execution requires RubyLLM >= 1.15 (before_tool_call callback)"
+        end
+
         if chat.respond_to?(:on_tool_call_batch)
           chat.on_tool_call_batch do |tool_calls|
-            raise Phronomy::Agent::ToolCallIntercepted.new(tool_calls)
+            raise build_tool_interception(chat, tool_calls, invocation)
           end
         end
 
-        if chat.respond_to?(:before_tool_call)
-          chat.before_tool_call do |tool_call|
-            raise Phronomy::Agent::ToolCallIntercepted.new(tool_call)
-          end
-        else
-          chat.on_tool_call do |tool_call|
-            raise Phronomy::Agent::ToolCallIntercepted.new(tool_call)
-          end
+        chat.before_tool_call do |tool_call|
+          raise build_tool_interception(chat, [tool_call], invocation)
         end
       end
       private_class_method :install_tool_interceptors
 
-      def self.calling_llm_action(agent, runtime, invocation)
-        user_message = invocation.user_message_sent ?
-          nil :
-          agent.send(:extract_message, invocation.input)
-        agent.send(
-          :check_cancellation!,
-          invocation.config,
-          "invocation cancelled before LLM call"
-        )
-        operation = Phronomy.configuration.llm_adapter.complete_async(
-          invocation.chat,
-          user_message,
-          config: invocation.config
+      def self.build_tool_interception(chat, fallback_tool_calls, invocation)
+        assistant_message = chat.messages.last
+        unless assistant_message&.respond_to?(:role) &&
+            assistant_message.role.to_sym == :assistant &&
+            assistant_message.respond_to?(:tool_calls)
+          raise Phronomy::Error,
+            "RubyLLM Tool callback fired before the complete assistant message was observable"
+        end
+
+        message_tool_calls = assistant_message.tool_calls
+        tool_calls = if message_tool_calls.respond_to?(:values)
+          message_tool_calls.values
+        else
+          Array(message_tool_calls)
+        end
+        tool_calls = Array(fallback_tool_calls) if tool_calls.empty?
+
+        ToolCallIntercepted.new(
+          tool_calls,
+          assistant_message: assistant_message,
+          assistant_outcome: ProviderCallOutcome.capture(assistant_message),
+          llm_call_id: invocation&.current_llm_call_id
         )
-        observe_llm_operation(
-          operation,
+      end
+      private_class_method :build_tool_interception
+
+      def self.calling_llm_action(agent, runtime, invocation)
+        prepare_and_start_llm_call(
+          agent,
+          runtime,
           invocation,
-          runtime: runtime,
           streaming: false
         )
         invocation
@@ -255,77 +259,175 @@ module Phronomy
       private_class_method :calling_llm_action
 
       def self.calling_llm_stream_action(agent, runtime, invocation)
-        user_message = invocation.user_message_sent ?
-          nil :
-          agent.send(:extract_message, invocation.input)
+        prepare_and_start_llm_call(
+          agent,
+          runtime,
+          invocation,
+          streaming: true
+        )
+        invocation
+      end
+      private_class_method :calling_llm_stream_action
+
+      def self.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
+      private_class_method :prepare_and_start_llm_call
+
+      def self.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"
         )
-
-        operation = Phronomy.configuration.llm_adapter.stream_async(
-          invocation.chat,
-          user_message,
-          config: invocation.config
-        ) do |chunk|
+        if replace_messages
+          invocation.chat = agent.send(:build_chat, model_config: projection.model_config)
           agent.send(
-            :check_cancellation!,
-            invocation.config,
-            "invocation cancelled during streaming"
-          )
-          post_to_invocation!(
-            runtime,
-            invocation.id,
-            :llm_stream_chunk,
-            {content: chunk.content}
+            :_apply_runtime_projection_to_chat,
+            invocation.chat,
+            projection,
+            invocation: invocation
           )
+          install_tool_interceptors(invocation.chat, invocation)
+          invocation.config[:phronomy_runtime_projection] = projection
         end
 
-        observe_llm_operation(
+        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: true
+          streaming: streaming
         )
-        invocation
+      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
-      private_class_method :calling_llm_stream_action
+      private_class_method :start_provider_call
 
-      def self.observe_llm_operation(
-        operation,
-        invocation,
-        runtime:,
-        streaming:
-      )
+      def self.observe_manifest_call(operation, activation, invocation, runtime:, streaming:)
         operation.on_complete do |response, error|
-          result = LLMOperationResult.new(
-            response: response,
+          activation.record_llm_result(
+            response: canonical_response_for(response, error),
             error: error,
             streaming: streaming
           )
-          event_type =
-            if error && !error.is_a?(ToolCallIntercepted)
-              :llm_failed
-            else
-              :llm_completed
-            end
-          post_to_invocation!(
+          post_llm_result(
             runtime,
-            invocation.id,
-            event_type,
-            result
+            invocation,
+            response,
+            error,
+            streaming: streaming
           )
         end
       end
-      private_class_method :observe_llm_operation
+      private_class_method :observe_manifest_call
 
-      def self.post_to_invocation!(
-        runtime,
-        invocation_id,
-        event_type,
-        payload
-      )
+      def self.canonical_response_for(response, error)
+        if error.is_a?(ToolCallIntercepted)
+          error.assistant_outcome || ProviderCallOutcome.capture(response)
+        else
+          ProviderCallOutcome.capture(response)
+        end
+      end
+      private_class_method :canonical_response_for
+
+      def self.post_preparation_failure(runtime, invocation, error, streaming:)
+        post_llm_result(runtime, invocation, nil, error, streaming: streaming)
+      end
+      private_class_method :post_preparation_failure
+
+      def self.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
+      private_class_method :post_llm_result
+
+      def self.post_to_invocation!(runtime, invocation_id, event_type, payload)
         accepted = runtime.event_loop.post_to_session(
           Phronomy::Event.new(
             type: event_type,

data/lib/phronomy/agent/agent_root.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Phronomy
+  module Agent
+    class AgentRoot
+      LIFECYCLE_STATUSES = %i[idle active suspended closed invalidated].freeze
+
+      ATTRIBUTES = %i[
+        agent_id agent_definition_id definition_version agent_revision
+        context_revision journal_position lifecycle_status transcript_generation
+        created_at updated_at metadata
+      ].freeze
+
+      attr_reader(*ATTRIBUTES)
+
+      def self.create(agent_id:, agent_definition_id:, definition_version:, metadata: {})
+        now = Time.now.utc.iso8601(6)
+        new(
+          agent_id: agent_id,
+          agent_definition_id: agent_definition_id,
+          definition_version: definition_version,
+          agent_revision: 0,
+          context_revision: 0,
+          journal_position: 0,
+          lifecycle_status: :idle,
+          transcript_generation: 0,
+          created_at: now,
+          updated_at: now,
+          metadata: metadata
+        )
+      end
+
+      def initialize(**attributes)
+        ATTRIBUTES.each do |name|
+          value = attributes.fetch(name)
+          value = value.to_sym if name == :lifecycle_status
+          instance_variable_set("@#{name}", Immutable.copy(value))
+        end
+        unless LIFECYCLE_STATUSES.include?(lifecycle_status)
+          raise ArgumentError, "unknown Agent lifecycle status: #{lifecycle_status.inspect}"
+        end
+        raise ArgumentError, "agent_revision must be non-negative" if agent_revision.negative?
+        raise ArgumentError, "context_revision must be non-negative" if context_revision.negative?
+        raise ArgumentError, "journal_position must be non-negative" if journal_position.negative?
+        Immutable.validate_canonical_json!(metadata, label: "Agent metadata")
+        freeze
+      end
+
+      def with(**changes)
+        values = to_h.transform_keys(&:to_sym).merge(changes)
+        values[:updated_at] = Time.now.utc.iso8601(6) unless changes.key?(:updated_at)
+        self.class.new(**values)
+      end
+
+      def to_h
+        ATTRIBUTES.to_h { |name| [name.to_s, public_send(name)] }
+      end
+
+      def self.from_h(hash)
+        new(**ATTRIBUTES.to_h { |name| [name, hash.fetch(name.to_s)] })
+      end
+    end
+  end
+end