phronomy 0.22.0 → 0.24.0

data/lib/phronomy/agent/agent_invocation_session_builder.rb

@@ -2,13 +2,6 @@
 
 module Phronomy
   module Agent
-    # Builds FSMSession instances for AgentInvocation objects.
-    #
-    # Offloaded/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
       AUTO_STATE_SET = {
         idle: true,
@@ -16,7 +9,6 @@ module Phronomy
         building_context: true,
         starting_tools: true,
         evaluating_tools: true,
-        dispatching_tools: true,
         recording_tool_results: true,
         output_filtering: true
       }.freeze
@@ -24,7 +16,7 @@ module Phronomy
       DECLARED_STATES = %i[
         idle filtering_input building_context calling_llm starting_tools
         evaluating_tools waiting_for_tools dispatching_tools
-        recording_tool_results suspended output_filtering completed blocked failed
+        recording_tool_results suspended output_filtering handed_off completed blocked failed
       ].freeze
 
       WAIT_STATES = %i[suspended].freeze
@@ -55,7 +47,8 @@ module Phronomy
           approval_policy: approval_policy,
           approval_listener: approval_listener,
           event_listener: on_event,
-          mode: mode
+          mode: mode,
+          execution_id: config.fetch(:execution_id)
         )
         build_session(
           agent_invocation: invocation,
@@ -87,15 +80,19 @@ module Phronomy
         resume_phase: nil
       )
         agent = agent_invocation.agent
-        actions = build_entry_actions(agent, runtime, mode: mode)
-        phase_machine = Agent::PhaseMachineBuilder.new(
-          entry_actions: actions
-        ).build
+        event_sink = Phronomy::FSMSession::EventSink.new(
+          event_loop: runtime.event_loop
+        )
+        agent_invocation.bind_event_sink!(event_sink)
+        actions = build_entry_actions(
+          agent, runtime, mode: mode, event_sink: event_sink
+        )
+        phase_machine = Agent::PhaseMachineBuilder.new(entry_actions: actions).build
         iterations = agent.class.max_iterations || 10
 
         Phronomy::FSMSession.new(
-          id: agent_invocation.id,
           context: agent_invocation,
+          event_sink: event_sink,
           entry_point: :idle,
           phase_machine_class: phase_machine,
           entry_actions: {},
@@ -113,22 +110,29 @@ module Phronomy
 
       def self.external_events
         tool_transitions = TOOL_EVENTS.to_h do |event_name|
-          [
-            event_name,
-            [{from: :waiting_for_tools, to: :evaluating_tools, guard: nil}]
-          ]
+          [event_name, [{from: :waiting_for_tools, to: :evaluating_tools, guard: nil}]]
         end
 
         tool_transitions.merge(
           llm_completed: [
-            {from: :calling_llm, to: :starting_tools, guard: ->(ctx) {
-              ctx.tool_call_pending?
-            }},
+            {from: :calling_llm, to: :failed, guard: ->(ctx) { ctx.callback_failed? }},
+            {from: :calling_llm, to: :failed, guard: ->(ctx) { ctx.handoff_failed? }},
+            {from: :calling_llm, to: :handed_off, guard: ->(ctx) { ctx.handoff_requested? }},
+            {from: :calling_llm, to: :starting_tools, guard: ->(ctx) { ctx.tool_call_pending? }},
             {from: :calling_llm, to: :output_filtering, guard: nil}
           ],
           llm_failed: [
             {from: :calling_llm, to: :failed, guard: nil}
           ],
+          llm_setup_failed: [
+            {from: :calling_llm, to: :failed, guard: nil}
+          ],
+          tool_setup_failed: [
+            {from: :dispatching_tools, to: :failed, guard: nil}
+          ],
+          tool_dispatch_prepared: [
+            {from: :dispatching_tools, to: :evaluating_tools, guard: nil}
+          ],
           resume: [
             {from: :suspended, to: :waiting_for_tools, guard: nil}
           ],
@@ -147,34 +151,22 @@ module Phronomy
       end
       private_class_method :external_events
 
-      def self.build_entry_actions(agent, runtime, mode:)
+      def self.build_entry_actions(agent, runtime, mode:, event_sink:)
         calling_action = if mode.to_sym == :stream
-          method(:calling_llm_stream_action).curry.call(agent, runtime)
+          method(:calling_llm_stream_action).curry.call(agent, runtime, event_sink)
         else
-          method(:calling_llm_action).curry.call(agent, runtime)
+          method(:calling_llm_action).curry.call(agent, runtime, event_sink)
         end
 
         {
-          filtering_input: [
-            method(:filtering_input_action).curry.call(agent)
-          ],
-          building_context: [
-            method(:building_context_action).curry.call(agent)
-          ],
+          filtering_input: [method(:filtering_input_action).curry.call(agent)],
+          building_context: [method(:building_context_action).curry.call(agent)],
           calling_llm: [calling_action],
-          starting_tools: [
-            method(:starting_tools_action).curry.call(runtime)
-          ],
-          dispatching_tools: [
-            method(:dispatching_tools_action).curry.call(runtime)
-          ],
-          recording_tool_results: [
-            method(:recording_tool_results_action)
-          ],
+          starting_tools: [method(:starting_tools_action).curry.call(runtime, event_sink)],
+          dispatching_tools: [method(:dispatching_tools_action).curry.call(runtime, event_sink)],
+          recording_tool_results: [method(:recording_tool_results_action)],
           suspended: [method(:suspended_action)],
-          output_filtering: [
-            method(:output_filtering_action).curry.call(agent)
-          ],
+          output_filtering: [method(:output_filtering_action).curry.call(agent)],
           failed: [method(:failed_action)]
         }
       end
@@ -195,15 +187,11 @@ module Phronomy
           projection,
           invocation: invocation
         )
-        install_tool_interceptors(invocation.chat, invocation)
         invocation
       end
       private_class_method :building_context_action
 
-      # 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)
+      def self.install_tool_interceptors(chat, llm_call_id:)
         unless chat.respond_to?(:before_tool_call)
           raise Phronomy::ConfigurationError,
             "Agent-owned Tool execution requires RubyLLM >= 1.15 (before_tool_call callback)"
@@ -211,17 +199,17 @@ module Phronomy
 
         if chat.respond_to?(:on_tool_call_batch)
           chat.on_tool_call_batch do |tool_calls|
-            raise build_tool_interception(chat, tool_calls, invocation)
+            raise build_tool_interception(chat, tool_calls, llm_call_id)
           end
         end
 
         chat.before_tool_call do |tool_call|
-          raise build_tool_interception(chat, [tool_call], invocation)
+          raise build_tool_interception(chat, [tool_call], llm_call_id)
         end
       end
       private_class_method :install_tool_interceptors
 
-      def self.build_tool_interception(chat, fallback_tool_calls, invocation)
+      def self.build_tool_interception(chat, fallback_tool_calls, llm_call_id)
         assistant_message = chat.messages.last
         unless assistant_message&.respond_to?(:role) &&
             assistant_message.role.to_sym == :assistant &&
@@ -231,94 +219,88 @@ module Phronomy
         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 = message_tool_calls.respond_to?(:values) ? message_tool_calls.values : Array(message_tool_calls)
         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
+          llm_call_id: llm_call_id
         )
       end
       private_class_method :build_tool_interception
 
-      def self.calling_llm_action(agent, runtime, invocation)
-        prepare_and_start_llm_call(
-          agent,
-          runtime,
-          invocation,
-          streaming: false
-        )
+      def self.calling_llm_action(agent, runtime, event_sink, invocation)
+        prepare_and_start_llm_call(agent, runtime, event_sink, invocation, streaming: false)
         invocation
       end
       private_class_method :calling_llm_action
 
-      def self.calling_llm_stream_action(agent, runtime, invocation)
-        prepare_and_start_llm_call(
-          agent,
-          runtime,
-          invocation,
-          streaming: true
-        )
+      def self.calling_llm_stream_action(agent, runtime, event_sink, invocation)
+        prepare_and_start_llm_call(agent, runtime, event_sink, 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)
+      def self.prepare_and_start_llm_call(agent, runtime, event_sink, invocation, streaming:)
+        # Callback failure is recorded synchronously on EventLoop before its
+        # explicit failure event is queued. Do not start a competing durable
+        # follow-up operation from the same execution revision while that failure
+        # event is waiting to terminalize the FSMSession.
+        return if invocation.callback_failed?
+
         if invocation.user_message_sent
-          preparation = runtime.offload.submit(on_full: :raise) 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
+          invocation.config.fetch(:phronomy_execution_coordinator).prepare_provider_dispatch(
+            invocation,
+            event_sink: event_sink,
+            streaming: streaming
+          )
         else
           start_provider_call(
             agent,
             runtime,
+            event_sink,
             invocation,
-            activation,
-            activation.runtime_projection,
+            invocation.config.fetch(:phronomy_runtime_projection),
             streaming: streaming,
             replace_messages: false
           )
         end
+      rescue => error
+        post_setup_failure(event_sink, error)
       end
       private_class_method :prepare_and_start_llm_call
 
-      def self.start_provider_call(
-        agent,
-        runtime,
-        invocation,
-        activation,
-        projection,
-        streaming:,
-        replace_messages:
+      # Continues a follow-up Provider Call after its durable preparation result
+      # has been validated/applied by ExecutionCoordinator on EventLoop.
+      # @api private
+      def self.start_prepared_provider_call(
+        agent:,
+        runtime:,
+        event_sink:,
+        invocation:,
+        projection:,
+        streaming:
       )
-        call_started = false
-        agent.send(
-          :check_cancellation!,
-          invocation.config,
-          "invocation cancelled before LLM call"
+        start_provider_call(
+          agent,
+          runtime,
+          event_sink,
+          invocation,
+          projection,
+          streaming: streaming,
+          replace_messages: true
         )
+      end
+
+      def self.start_provider_call(
+        agent, runtime, event_sink, invocation, projection,
+        streaming:, replace_messages:
+      )
+        call_context = trace_handle = nil
+        config = invocation.config
+        agent.send(:check_cancellation!, config, "invocation cancelled before LLM call")
         if replace_messages
           invocation.chat = agent.send(:build_chat, model_config: projection.model_config)
           agent.send(
@@ -327,69 +309,83 @@ module Phronomy
             projection,
             invocation: invocation
           )
-          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))
+        call_context = invocation.begin_llm_call!(projection)
+        install_tool_interceptors(
+          invocation.chat,
+          llm_call_id: call_context.fetch(:llm_call_id)
+        )
         message = projection.ask_message
+        chat = invocation.chat
+        trace_handle = Phronomy::Tracing::Automatic.start(
+          "llm.call",
+          input: message,
+          agent_id: agent.agent_id,
+          execution_id: invocation.execution_id,
+          llm_call_id: call_context.fetch(:llm_call_id),
+          mode: invocation.mode,
+          streaming: streaming,
+          **agent.send(:_build_caller_meta, config)
+        )
 
         operation = if streaming
           Phronomy.configuration.llm_adapter.stream_async(
-            invocation.chat,
-            message,
-            config: invocation.config
+            chat, message, config: 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}
+            token = config[:cancellation_token]
+            token&.raise_if_cancelled!("invocation cancelled during streaming")
+            post_stream_chunk(
+              event_sink,
+              call_context.fetch(:llm_call_id),
+              chunk.content
             )
           end
         else
           Phronomy.configuration.llm_adapter.complete_async(
-            invocation.chat,
-            message,
-            config: invocation.config
+            chat, message, config: config
           )
         end
+        runtime.event_loop.supervise_agent_operation(
+          invocation.execution_id,
+          operation
+        )
         observe_manifest_call(
           operation,
-          activation,
-          invocation,
-          runtime: runtime,
+          event_sink,
+          call_context,
+          trace_handle,
           streaming: streaming
         )
       rescue => error
-        if call_started
-          activation.record_llm_result(
-            response: canonical_response_for(nil, error),
-            error: error,
+        finish_provider_trace(trace_handle, nil, error)
+        if call_context
+          post_llm_result(
+            event_sink,
+            call_context,
+            nil,
+            error,
             streaming: streaming
           )
+        else
+          post_setup_failure(event_sink, error)
         end
-        post_llm_result(runtime, invocation, nil, error, streaming: streaming)
       end
       private_class_method :start_provider_call
 
-      def self.observe_manifest_call(operation, activation, invocation, runtime:, streaming:)
+      def self.observe_manifest_call(
+        operation,
+        event_sink,
+        call_context,
+        trace_handle,
+        streaming:
+      )
         operation.on_complete do |response, error|
-          activation.record_llm_result(
-            response: canonical_response_for(response, error),
-            error: error,
-            streaming: streaming
-          )
+          finish_provider_trace(trace_handle, response, error)
           post_llm_result(
-            runtime,
-            invocation,
+            event_sink,
+            call_context,
             response,
             error,
             streaming: streaming
@@ -398,22 +394,27 @@ module Phronomy
       end
       private_class_method :observe_manifest_call
 
-      def self.canonical_response_for(response, error)
-        if error.is_a?(ToolCallIntercepted)
-          error.assistant_outcome || ProviderCallOutcome.capture(response)
-        else
-          ProviderCallOutcome.capture(response)
+      def self.finish_provider_trace(trace_handle, response, error)
+        control_transfer = error.is_a?(ToolCallIntercepted)
+        trace_output = control_transfer ?
+          (error.assistant_outcome || error.assistant_message) : response
+        trace_error = control_transfer ? nil : error
+        usage_source = control_transfer ? error.assistant_message : response
+        usage = if usage_source&.respond_to?(:tokens)
+          Phronomy::TokenUsage.from_tokens(usage_source.tokens)
         end
+        Phronomy::Tracing::Automatic.finish(
+          trace_handle,
+          output: trace_output,
+          usage: usage,
+          error: trace_error
+        )
       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
+      private_class_method :finish_provider_trace
 
-      def self.post_llm_result(runtime, invocation, response, error, streaming:)
+      def self.post_llm_result(event_sink, call_context, response, error, streaming:)
         result = LLMOperationResult.new(
+          llm_call_id: call_context.fetch(:llm_call_id),
           response: response,
           error: error,
           streaming: streaming
@@ -423,46 +424,65 @@ module Phronomy
         else
           :llm_completed
         end
-        post_to_invocation!(runtime, invocation.id, event_type, result)
+        post_session_event!(event_sink, 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,
-            target_id: invocation_id,
-            payload: payload
-          )
+      def self.post_stream_chunk(event_sink, llm_call_id, content)
+        post_session_event!(
+          event_sink,
+          :llm_stream_chunk,
+          {llm_call_id: llm_call_id.to_s.freeze, content: content}.freeze
         )
-        return if accepted
+      end
+      private_class_method :post_stream_chunk
+
+      def self.post_setup_failure(event_sink, error)
+        post_session_event!(event_sink, :llm_setup_failed, error)
+      end
+      private_class_method :post_setup_failure
+
+      def self.post_session_event!(event_sink, event_type, payload)
+        return if event_sink.post(event_type, payload)
 
         Phronomy.configuration.logger&.warn(
           "[Phronomy] Dropped late #{event_type.inspect} for " \
-          "AgentInvocation #{invocation_id}"
+          "FSMSession #{event_sink.fsm_session_id}"
         )
       end
-      private_class_method :post_to_invocation!
+      private_class_method :post_session_event!
 
-      def self.starting_tools_action(runtime, invocation)
+      def self.starting_tools_action(runtime, parent_event_sink, invocation)
         children = invocation.pending_tool_calls.map do |tool_call|
           tool = invocation.chat.tools[tool_call.name.to_sym]
+          tool_invocation_id =
+            RecoverySupport.semantic_tool_id(
+              execution_id: invocation.execution_id,
+              llm_call_id: invocation.tool_batch_llm_call_id,
+              tool_call_id: (
+                tool_call.respond_to?(:id) ? tool_call.id : nil
+              ),
+              tool_name: tool_call.name
+            )
+
           if tool
             ToolInvocation.new(
-              parent_agent_invocation_id: invocation.id,
+              execution_id: invocation.execution_id,
               agent: invocation.agent,
               tool: tool,
               tool_call: tool_call,
               config: invocation.config,
               approval_policy: invocation.approval_policy,
-              approval_context: invocation.approval_context
+              approval_context: invocation.approval_context,
+              id: tool_invocation_id
             )
           else
             ToolInvocation.missing(
-              parent_agent_invocation_id: invocation.id,
+              execution_id: invocation.execution_id,
               agent: invocation.agent,
               tool_call: tool_call,
-              config: invocation.config
+              config: invocation.config,
+              id: tool_invocation_id
             )
           end
         end
@@ -471,45 +491,65 @@ module Phronomy
         children.reject(&:terminal?).each do |child|
           session = ToolInvocationSessionBuilder.build(
             tool_invocation: child,
+            parent_event_sink: parent_event_sink,
             runtime: runtime
           )
-          register_child_session(runtime, child, session)
+          register_child_session(
+            runtime,
+            child,
+            session,
+            parent_event_sink
+          )
         end
         invocation
       end
       private_class_method :starting_tools_action
 
-      def self.dispatching_tools_action(runtime, invocation)
-        invocation.tool_invocations
-          .select(&:authorized?)
-          .each do |child|
-            session = ToolInvocationSessionBuilder.build_for_resume(
-              tool_invocation: child,
-              resume_event: :dispatch,
-              resume_phase: :authorized,
-              runtime: runtime
-            )
-            register_child_session(runtime, child, session)
-          end
+      def self.dispatching_tools_action(_runtime, parent_event_sink, invocation)
+        invocation.config.fetch(:phronomy_execution_coordinator).prepare_tool_dispatch(
+          invocation,
+          event_sink: parent_event_sink
+        )
         invocation
       end
       private_class_method :dispatching_tools_action
 
-      def self.register_child_session(runtime, child, session)
-        completion = Phronomy::Task.deferred(
-          name: "tool-session:#{child.id}"
-        )
+      # Continues Tool physical dispatch after the operation-specific durable
+      # preparation has been confirmed and applied by ExecutionCoordinator.
+      # @api private
+      def self.start_prepared_tool_dispatch(
+        runtime:,
+        event_sink:,
+        invocation:
+      )
+        invocation.tool_invocations.select(&:authorized?).each do |child|
+          session = ToolInvocationSessionBuilder.build_for_resume(
+            tool_invocation: child,
+            parent_event_sink: event_sink,
+            resume_event: :dispatch,
+            resume_phase: :authorized,
+            runtime: runtime
+          )
+          begin
+            register_child_session(runtime, child, session, event_sink)
+          rescue => error
+            child.mark_framework_failed!(error)
+            event_sink.post(:tool_failed, {tool_invocation_id: child.id})
+          end
+        end
+        post_session_event!(event_sink, :tool_dispatch_prepared, nil)
+        invocation
+      end
+
+      def self.register_child_session(runtime, child, session, parent_event_sink)
+        completion = Phronomy::Task.deferred(name: "tool-session:#{child.id}")
         completion.on_complete do |_result, error|
           next unless error
 
+          # Tool FSMSession completion is settled by EventLoop, so this callback
+          # also executes on EventLoop and remains inside the single-writer domain.
           child.mark_framework_failed!(error)
-          runtime.event_loop.post_to_session(
-            Phronomy::Event.new(
-              type: :tool_failed,
-              target_id: child.parent_agent_invocation_id,
-              payload: {tool_invocation_id: child.id}
-            )
-          )
+          parent_event_sink.post(:tool_failed, {tool_invocation_id: child.id})
         end
         runtime.event_loop.register(session, completion: completion)
       end
@@ -526,18 +566,12 @@ module Phronomy
       private_class_method :suspended_action
 
       def self.failed_action(invocation)
-        raise(
-          invocation.error ||
-          Phronomy::ToolError.new("Agent invocation failed")
-        )
+        raise(invocation.error || Phronomy::ToolError.new("Agent invocation failed"))
       end
       private_class_method :failed_action
 
       def self.output_filtering_action(agent, invocation)
-        invocation.output = agent.send(
-          :run_output_filters!,
-          invocation.output
-        )
+        invocation.output = agent.send(:run_output_filters!, invocation.output)
         invocation
       rescue Phronomy::FilterBlockError => error
         invocation.output_blocked = true