phronomy 0.15.1 → 0.17.0

data/lib/phronomy/agent/agent_execution.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "time"
+
+module Phronomy
+  module Agent
+    class AgentExecution
+      ACTIVE_STATUSES = %i[preparing active suspended].freeze
+      TERMINAL_STATUSES = %i[completed failed cancelled rejected blocked].freeze
+      TRANSITIONS = {
+        preparing: %i[preparing active failed cancelled blocked],
+        active: %i[active suspended completed failed cancelled rejected blocked],
+        suspended: %i[suspended active failed cancelled],
+        completed: %i[completed],
+        failed: %i[failed],
+        cancelled: %i[cancelled],
+        rejected: %i[rejected],
+        blocked: %i[blocked]
+      }.freeze
+
+      ATTRIBUTES = %i[
+        execution_id agent_id execution_revision status phase
+        base_agent_revision base_context_revision base_journal_position
+        working_records llm_calls approval_request result_ref error_ref
+        created_at updated_at terminal_reason metadata
+      ].freeze
+      attr_reader(*ATTRIBUTES)
+
+      def self.start(agent_root:, input_record:, metadata: {})
+        now = Time.now.utc.iso8601(6)
+        new(
+          execution_id: SecureRandom.uuid,
+          agent_id: agent_root.agent_id,
+          execution_revision: 0,
+          status: :preparing,
+          phase: :preparing,
+          base_agent_revision: agent_root.agent_revision,
+          base_context_revision: agent_root.context_revision,
+          base_journal_position: agent_root.journal_position,
+          working_records: [input_record],
+          llm_calls: [],
+          approval_request: nil,
+          result_ref: nil,
+          error_ref: nil,
+          created_at: now,
+          updated_at: now,
+          terminal_reason: nil,
+          metadata: metadata
+        )
+      end
+
+      def initialize(**attributes)
+        ATTRIBUTES.each do |name|
+          value = attributes.fetch(name)
+          value = value.to_sym if %i[status phase].include?(name)
+          instance_variable_set("@#{name}", Immutable.copy(value))
+        end
+        raise ArgumentError, "unknown execution status: #{status.inspect}" unless TRANSITIONS.key?(status)
+        raise ArgumentError, "execution_revision must be non-negative" if execution_revision.negative?
+        Immutable.validate_canonical_json!(metadata, label: "Execution metadata")
+        if approval_request
+          Immutable.validate_canonical_json!(approval_request, label: "Approval request")
+        end
+        freeze
+      end
+
+      def active?
+        ACTIVE_STATUSES.include?(status)
+      end
+
+      def terminal?
+        TERMINAL_STATUSES.include?(status)
+      end
+
+      def with(**changes)
+        next_status = changes.fetch(:status, status).to_sym
+        unless TRANSITIONS.fetch(status).include?(next_status)
+          raise ArgumentError, "illegal AgentExecution transition: #{status} -> #{next_status}"
+        end
+        values = ATTRIBUTES.to_h { |name| [name, public_send(name)] }.merge(changes)
+        values[:execution_revision] = execution_revision + 1 unless changes.key?(:execution_revision)
+        values[:updated_at] = Time.now.utc.iso8601(6) unless changes.key?(:updated_at)
+        self.class.new(**values)
+      end
+
+      def to_h
+        ATTRIBUTES.to_h do |name|
+          value = public_send(name)
+          value = value.map(&:to_h) if name == :working_records
+          value = value.map(&:to_h) if name == :llm_calls
+          [name.to_s, value]
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/agent/agent_execution_activation.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "time"
+
+module Phronomy
+  module Agent
+    class AgentExecutionActivation
+      attr_reader :execution_id, :agent, :application_listener, :coordinator,
+        :base_manifest
+      attr_accessor :invocation, :session
+
+      def initialize(
+        execution:,
+        agent:,
+        runtime_projection:,
+        coordinator:,
+        application_listener: nil
+      )
+        @execution_id = execution.execution_id
+        @execution = execution
+        @agent = agent
+        @runtime_projection = runtime_projection
+        @base_manifest = runtime_projection.manifest
+        @coordinator = coordinator
+        @application_listener = application_listener
+        @mutex = Mutex.new
+        @active_call = nil
+        @llm_results = []
+        @runtime_events = []
+        @callback_errors = []
+      end
+
+      def execution
+        @mutex.synchronize { @execution }
+      end
+
+      def replace_execution(value)
+        @mutex.synchronize { @execution = value }
+      end
+
+      def runtime_projection
+        @mutex.synchronize { @runtime_projection }
+      end
+
+      def replace_runtime_projection(value)
+        @mutex.synchronize { @runtime_projection = value }
+      end
+
+      # Allocates Provider Call identity before transport begins. This identity is
+      # provenance only; Context selection must not use it as a semantic boundary.
+      def begin_llm_call(projection)
+        call_context = {
+          llm_call_id: SecureRandom.uuid,
+          manifest_ref: projection.manifest_ref,
+          started_at: Time.now.utc.iso8601(6)
+        }.freeze
+        @mutex.synchronize do
+          if @active_call
+            raise Phronomy::Error,
+              "cannot start a Provider Call while another Provider Call is active"
+          end
+          @runtime_projection = projection
+          @active_call = call_context
+        end
+        call_context
+      end
+
+      def record_llm_result(response:, error:, streaming:)
+        @mutex.synchronize do
+          active_call = @active_call
+          unless active_call
+            raise Phronomy::Error, "LLM result arrived without an active Provider Call"
+          end
+          @llm_results << {
+            llm_call_id: active_call.fetch(:llm_call_id),
+            response: response,
+            error: error,
+            streaming: streaming,
+            manifest_ref: active_call.fetch(:manifest_ref),
+            started_at: active_call.fetch(:started_at)
+          }
+          @active_call = nil
+        end
+      end
+
+      def runtime_snapshot
+        @mutex.synchronize do
+          {
+            llm_results: @llm_results.dup,
+            runtime_events: @runtime_events.dup,
+            active_call: @active_call&.dup
+          }
+        end
+      end
+
+      def acknowledge_runtime_snapshot(snapshot)
+        @mutex.synchronize do
+          @llm_results.shift(snapshot.fetch(:llm_results).length)
+          @runtime_events.shift(snapshot.fetch(:runtime_events).length)
+          if snapshot[:active_call] && @active_call == snapshot[:active_call]
+            @active_call = nil
+          end
+        end
+      end
+
+      ApplicationCallbackFailure = Data.define(:event_type, :error) do
+        def to_stream_callback_error
+          wrapped = Phronomy::StreamCallbackError.new(
+            event_type: event_type, original_error: error, result: nil
+          )
+          begin
+            raise wrapped, cause: error
+          rescue Phronomy::StreamCallbackError => caught
+            caught.set_backtrace(error.backtrace)
+            caught
+          end
+        end
+      end
+
+      attr_reader :callback_failure
+
+      def callback_failed?
+        @mutex.synchronize { !@callback_failure.nil? }
+      end
+
+      # Canonical runtime recording is independent of Application callback health.
+      # Once an event is observed it is appended even after a listener has failed.
+      def record_event(event)
+        listener = @mutex.synchronize do
+          @runtime_events << event
+          @callback_failure ? nil : @application_listener
+        end
+        return unless listener
+
+        listener.call(event)
+      rescue => callback_error
+        failure = ApplicationCallbackFailure.new(
+          event_type: event.type, error: callback_error
+        )
+        @mutex.synchronize do
+          @callback_failure ||= failure
+          @application_listener = nil
+        end
+        notify_callback_failure(failure)
+      end
+
+      private
+
+      def notify_callback_failure(failure)
+        invocation = @mutex.synchronize { @invocation }
+        if invocation
+          accepted = Phronomy::Runtime.instance.event_loop.post_to_session(
+            Phronomy::Event.new(
+              type: :application_callback_failed,
+              target_id: invocation.id,
+              payload: {failure: failure}
+            )
+          )
+          unless accepted
+            Phronomy.configuration.logger&.warn(
+              "[Phronomy] Callback failure recorded but could not notify FSM: execution_id=#{@execution_id}"
+            )
+          end
+        end
+        Phronomy.configuration.logger&.warn(
+          "[Phronomy] Application event listener failed: #{failure.error.class}: #{failure.error.message}"
+        )
+      end
+    end
+  end
+end

data/lib/phronomy/agent/agent_invocation.rb

@@ -26,8 +26,9 @@ module Phronomy
         llm_failed
       ].freeze
 
+      CALLBACK_FAILED_EVENTS = %i[application_callback_failed].freeze
+
       attr_accessor :input,
-        :messages,
         :chat,
         :output,
         :usage,
@@ -50,23 +51,22 @@ module Phronomy
         :tool_invocations,
         :session_id,
         :phase,
-        :mode
+        :mode,
+        :current_llm_call_id,
+        :tool_batch_llm_call_id
 
       def initialize(
         agent:,
         input:,
-        messages:,
         config:,
         approval_policy: nil,
         approval_listener: nil,
         event_listener: nil,
-        stream_listener: nil,
         mode: nil,
         id: nil
       )
         @agent = agent
         @input = input
-        @messages = Array(messages)
         @config = config
         @thread_id = config[:thread_id]
         @id = (id || config[:agent_invocation_id] || SecureRandom.uuid).to_s
@@ -76,8 +76,8 @@ module Phronomy
         end
         @approval_policy = invocation_policy || approval_policy
         @approval_listener = approval_listener
-        @event_listener = event_listener || stream_listener
-        @mode = (mode || (stream_listener ? :stream : :invoke)).to_sym
+        @event_listener = event_listener
+        @mode = (mode || :invoke).to_sym
 
         @chat = nil
         @output = nil
@@ -96,15 +96,8 @@ module Phronomy
         @error = nil
         @session_id = nil
         @phase = nil
-      end
-
-      # Compatibility aliases for existing internal callers.
-      def stream_listener
-        @event_listener
-      end
-
-      def stream_listener=(listener)
-        @event_listener = listener
+        @current_llm_call_id = nil
+        @tool_batch_llm_call_id = nil
       end
 
       def streaming?
@@ -116,6 +109,11 @@ module Phronomy
         @phase = phase
       end
 
+      def begin_llm_call!(llm_call_id)
+        @current_llm_call_id = llm_call_id.to_s
+        self
+      end
+
       def pending_tool_calls=(calls)
         @pending_tool_calls = Array(calls)
       end
@@ -128,6 +126,7 @@ module Phronomy
         @pending_tool_calls = []
         @tool_invocations = []
         @approval_request = nil
+        @tool_batch_llm_call_id = nil
       end
 
       def handle_fsm_event(event)
@@ -146,6 +145,11 @@ module Phronomy
           return true
         end
 
+        if CALLBACK_FAILED_EVENTS.include?(event.type)
+          @error ||= event.payload.fetch(:failure).to_stream_callback_error
+          return true
+        end
+
         return false unless TOOL_EVENT_TYPES.include?(event.type)
 
         invocation = tool_invocation(
@@ -164,36 +168,19 @@ module Phronomy
         true
       end
 
-      # Deprecated internal compatibility hook. FSMSession no longer calls
-      # this method; asynchronous results enter through explicit events.
-      def apply_fsm_action_result(result)
-        event_type =
-          if result.respond_to?(:error) &&
-              result.error &&
-              !result.error.is_a?(ToolCallIntercepted)
-            :llm_failed
-          else
-            :llm_completed
-          end
-        handle_fsm_event(
-          Phronomy::Event.new(
-            type: event_type,
-            target_id: @id,
-            payload: result
-          )
-        )
-        self
-      end
-
-      def accept_tool_calls!(tool_calls)
+      def accept_tool_calls!(tool_calls, llm_call_id: nil)
         @user_message_sent = true
         @pending_tool_calls = Array(tool_calls)
-        @messages = @chat.messages
+        @tool_batch_llm_call_id = (llm_call_id || @current_llm_call_id)&.to_s
+        @current_llm_call_id = nil
         @pending_tool_calls.each do |tool_call|
           deliver_event(
             StreamEvent.new(
               type: :tool_call,
-              payload: {tool_call: tool_call}
+              payload: {
+                tool_call: tool_call,
+                llm_call_id: @tool_batch_llm_call_id
+              }.compact
             )
           )
         end
@@ -208,8 +195,8 @@ module Phronomy
         @user_message_sent = true
         @output = response.content
         @usage = Phronomy::TokenUsage.from_tokens(response.tokens)
-        @messages = @chat.messages
         @pending_tool_calls = []
+        @current_llm_call_id = nil
         self
       end
 
@@ -255,9 +242,10 @@ module Phronomy
 
       def record_tool_results!
         @tool_invocations.each do |invocation|
+          tool_content = invocation.result.to_s
           @chat.add_message(
             role: :tool,
-            content: invocation.result.to_s,
+            content: tool_content,
             tool_call_id: invocation.tool_call_id
           )
           deliver_event(
@@ -266,12 +254,17 @@ module Phronomy
               payload: {
                 tool_call_id: invocation.tool_call_id,
                 tool_name: invocation.tool_name,
-                tool_result: invocation.result
-              }
+                tool_result: invocation.result,
+                tool_message: {
+                  "role" => "tool",
+                  "content" => tool_content,
+                  "tool_call_id" => invocation.tool_call_id.to_s
+                },
+                llm_call_id: @tool_batch_llm_call_id
+              }.compact
             )
           )
         end
-        @messages = @chat.messages
         clear_tool_batch!
         self
       end
@@ -361,6 +354,7 @@ module Phronomy
         end
 
         if event.type == :llm_failed
+          @current_llm_call_id = nil
           @error = result.error ||
             Phronomy::Error.new("LLM operation failed without an error")
           return
@@ -368,8 +362,12 @@ module Phronomy
 
         if result.error
           if result.error.is_a?(ToolCallIntercepted)
-            accept_tool_calls!(result.error.tool_calls)
+            accept_tool_calls!(
+              result.error.tool_calls,
+              llm_call_id: result.error.llm_call_id
+            )
           else
+            @current_llm_call_id = nil
             @error = result.error
           end
         else