phronomy 0.15.0 → 0.16.0

data/lib/phronomy/agent/agent_invocation_session_builder.rb

@@ -132,6 +132,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
@@ -206,30 +217,58 @@ module Phronomy
           invocation.chat,
           invocation.config
         )
-        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.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
+        )
+      end
+      private_class_method :build_tool_interception
+
       def self.calling_llm_action(agent, runtime, invocation)
         user_message = invocation.user_message_sent ?
           nil :

data/lib/phronomy/agent/agent_root.rb

@@ -0,0 +1,67 @@
+# 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 memory_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,
+          memory_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

data/lib/phronomy/agent/async_event_api.rb

@@ -2,39 +2,17 @@
 
 module Phronomy
   module Agent
-    # Symmetric Agent async event contract layered onto Agent::Base.
-    #
-    # invoke_async and stream_async share lifecycle/tool events. stream_async
-    # additionally emits :token events. The returned Task remains a normal Task
-    # and is settled after the terminal event listener returns.
-    #
-    # @api private
+    # Public Agent execution API. Agent instances are always stateful and all
+    # operations are coordinated through Phronomy::Persistence.
     module AsyncEventApi
-      def invoke(
-        input,
-        messages: [],
-        thread_id: nil,
-        config: {},
-        invocation_context: nil,
-        on_event: nil
-      )
+      def invoke(input, thread_id: nil, config: {}, invocation_context: nil, on_event: nil)
         if invocation_context
-          thread_id, config = _apply_invocation_context(
-            thread_id,
-            config,
-            invocation_context
-          )
+          thread_id, config = _apply_invocation_context(thread_id, config, invocation_context)
         end
         _check_scheduler_reentrancy(:invoke, :invoke_async)
-
-        trace(
-          "agent.invoke",
-          input: input,
-          **_build_caller_meta(config)
-        ) do |_span|
+        trace("agent.invoke", input: input, **_build_caller_meta(config)) do |_span|
           result = invoke_async(
             input,
-            messages: messages,
             thread_id: thread_id,
             config: config,
             on_event: on_event
@@ -45,7 +23,6 @@ module Phronomy
 
       def invoke_async(
         input,
-        messages: [],
         thread_id: nil,
         config: {},
         invocation_context: nil,
@@ -53,81 +30,22 @@ module Phronomy
         on_event: nil
       )
         if invocation_context
-          thread_id, config = _apply_invocation_context(
-            thread_id,
-            config,
-            invocation_context
-          )
+          thread_id, config = _apply_invocation_context(thread_id, config, invocation_context)
         end
-
-        result_task = Phronomy::Task.deferred(
-          name:
-            "agent-#{(self.class.name || "anonymous").downcase}-async"
-        )
-        approval_snapshot = _approval_configuration_snapshot(
-          on_tool_approval_required
-        )
-        _start_invocation(
-          result_task,
+        approval = _approval_configuration_snapshot(on_tool_approval_required)
+        execution_coordinator.start(
           input,
-          messages: messages,
           thread_id: thread_id,
           config: config,
-          approval_snapshot: approval_snapshot,
           mode: :invoke,
+          approval_policy: approval[:policy],
+          approval_listener: approval[:listener],
           on_event: on_event
         )
-        result_task
-      end
-
-      def stream_async(
-        input,
-        messages: [],
-        thread_id: nil,
-        config: {},
-        invocation_context: nil,
-        on_tool_approval_required: nil,
-        on_event: nil,
-        &block
-      )
-        listener = resolve_event_listener(on_event, block)
-        unless listener
-          raise ArgumentError,
-            "stream_async requires on_event: or a block"
-        end
-
-        if invocation_context
-          thread_id, config = _apply_invocation_context(
-            thread_id,
-            config,
-            invocation_context
-          )
-        end
-
-        result_task = Phronomy::Task.deferred(
-          name:
-            "agent-#{(self.class.name || "anonymous").downcase}" \
-            "-stream-async"
-        )
-        approval_snapshot = _approval_configuration_snapshot(
-          on_tool_approval_required
-        )
-        _start_invocation(
-          result_task,
-          input,
-          messages: messages,
-          thread_id: thread_id,
-          config: config,
-          approval_snapshot: approval_snapshot,
-          mode: :stream,
-          on_event: listener
-        )
-        result_task
       end
 
       def stream(
         input,
-        messages: [],
         thread_id: nil,
         config: {},
         invocation_context: nil,
@@ -136,335 +54,79 @@ module Phronomy
         &block
       )
         listener = resolve_event_listener(on_event, block)
-        unless listener
-          raise ArgumentError,
-            "stream requires on_event: or a block"
-        end
-
+        raise ArgumentError, "stream requires on_event: or a block" unless listener
         if invocation_context
-          thread_id, config = _apply_invocation_context(
-            thread_id,
-            config,
-            invocation_context
-          )
+          thread_id, config = _apply_invocation_context(thread_id, config, invocation_context)
         end
         _check_scheduler_reentrancy(:stream, :stream_async)
-
-        trace(
-          "agent.stream",
-          input: input,
-          **_build_caller_meta(config)
-        ) do |_span|
+        trace("agent.stream", input: input, **_build_caller_meta(config)) do |_span|
           result = stream_async(
             input,
-            messages: messages,
             thread_id: thread_id,
             config: config,
-            on_tool_approval_required:
-              on_tool_approval_required,
+            on_tool_approval_required: on_tool_approval_required,
             on_event: listener
           ).wait_result
           [result, result[:usage]]
         end
       end
 
-      private
-
-      def resolve_event_listener(keyword_listener, block_listener)
-        if keyword_listener && block_listener
-          raise ArgumentError,
-            "Provide either on_event: or a block, not both"
-        end
-        keyword_listener || block_listener
-      end
-
-      # Installs the Application listener before EventLoop admission.
-      # Cancellation is checked by the first Agent entry action on the EventLoop
-      # thread so even pre-cancelled invocations produce a terminal event before
-      # the returned Task settles.
-      def _start_invocation(
-        result_task,
+      def stream_async(
         input,
-        messages:,
-        thread_id:,
-        config:,
-        approval_snapshot:,
-        mode: :invoke,
-        on_event: nil
-      )
-        effective_config =
-          thread_id ? config.merge(thread_id: thread_id) : config
-        runtime = Phronomy::Runtime.instance
-        event_loop = runtime.event_loop
-        session = Agent::AgentInvocationSessionBuilder.build(
-          agent: self,
-          input: input,
-          messages: messages,
-          config: effective_config,
-          approval_policy: approval_snapshot[:policy],
-          approval_listener: approval_snapshot[:listener],
-          mode: mode,
-          on_event: on_event,
-          runtime: runtime
-        )
-        callback_error_policy =
-          Phronomy.configuration.stream_callback_error_policy
-        source_task = Phronomy::Task.deferred(
-          name: "#{result_task.name}-source"
-        )
-        source_task.on_complete do |invocation, error|
-          completed_invocation = invocation || session.context
-          _handle_agent_completion(
-            result_task: result_task,
-            invocation: completed_invocation,
-            error: error,
-            mode: mode,
-            listener: on_event,
-            event_loop: event_loop,
-            callback_error_policy: callback_error_policy
-          )
-        end
-
-        event_loop.register(session, completion: source_task)
-      rescue => error
-        _fail_result_task(result_task, error)
-      end
-
-      def _handle_agent_completion(
-        result_task:,
-        invocation:,
-        error:,
-        mode:,
-        listener:,
-        event_loop:,
-        callback_error_policy:
+        thread_id: nil,
+        config: {},
+        invocation_context: nil,
+        on_tool_approval_required: nil,
+        on_event: nil,
+        &block
       )
-        if listener && !event_loop.current?
-          completion_error = error || Phronomy::Error.new(
-            "Agent event delivery occurred outside the EventLoop"
-          )
-          _fail_result_task(
-            result_task,
-            _translated_error(completion_error)
-          )
-          return
-        end
-
-        result = nil
-        execution_error = nil
-        begin
-          raise error if error
-
-          result = _extract_invoke_result(invocation)
-        rescue => caught
-          execution_error = _translated_error(caught)
-        end
-        if execution_error
-          execution_error = normalize_terminal_error(
-            execution_error,
-            invocation
-          )
-        end
-
-        if execution_error
-          terminal_event = StreamEvent.new(
-            type: terminal_error_event_type(execution_error),
-            payload: {error: execution_error}
-          )
-          callback_error = _deliver_stream_event(
-            listener,
-            terminal_event
-          )
-          if callback_error
-            report_agent_event_callback_error(
-              callback_error,
-              event: terminal_event,
-              invocation_id: invocation&.id,
-              callback_error_policy: callback_error_policy
-            )
-          end
-
-          # Listener failure never replaces an Agent execution failure.
-          _fail_result_task(result_task, execution_error)
-          return
-        end
-
-        terminal_event = _build_stream_terminal_event(result)
-        callback_error = _deliver_stream_event(
-          listener,
-          terminal_event
-        )
-
-        unless callback_error
-          _complete_result_task(result_task, result)
-          return
+        listener = resolve_event_listener(on_event, block)
+        raise ArgumentError, "stream_async requires on_event: or a block" unless listener
+        if invocation_context
+          thread_id, config = _apply_invocation_context(thread_id, config, invocation_context)
         end
-
-        report_agent_event_callback_error(
-          callback_error,
-          event: terminal_event,
-          invocation_id: invocation&.id,
-          callback_error_policy: callback_error_policy
+        approval = _approval_configuration_snapshot(on_tool_approval_required)
+        execution_coordinator.start(
+          input,
+          thread_id: thread_id,
+          config: config,
+          mode: :stream,
+          approval_policy: approval[:policy],
+          approval_listener: approval[:listener],
+          on_event: listener
         )
-
-        if callback_error_policy == :fail_task
-          wrapped = _build_stream_callback_error(
-            event_type: terminal_event.type,
-            callback_error: callback_error,
-            result: result
-          )
-          _fail_result_task(result_task, wrapped)
-        else
-          _complete_result_task(result_task, result)
-        end
       end
 
-      def terminal_error_event_type(error)
-        case error
-        when Phronomy::TimeoutError
-          :timeout
-        when Phronomy::CancellationError
-          :cancelled
-        else
-          :error
-        end
+      def approve(execution_id, approval_request_id:, approved: true, config: {})
+        _check_scheduler_reentrancy(:approve, :approve_async)
+        approve_async(
+          execution_id,
+          approval_request_id: approval_request_id,
+          approved: approved,
+          config: config
+        ).wait_result
       end
 
-      def normalize_terminal_error(error, invocation)
-        return error unless error.is_a?(Phronomy::CancellationError)
-        return error unless invocation_timeout_expired?(invocation)
-
-        timeout_error = Phronomy::TimeoutError.new(error.message)
-        timeout_error.set_backtrace(error.backtrace)
-        timeout_error
-      end
-
-      def invocation_timeout_expired?(invocation)
-        config = invocation&.config || {}
-        invocation_context = config[:invocation_context]
-        deadline = invocation_context&.deadline
-        return true if deadline&.expired?
-
-        token = config[:cancellation_token]
-        return false unless token
-
-        remaining =
-          if token.respond_to?(:remaining_monotonic_seconds)
-            token.remaining_monotonic_seconds
-          end
-        return true if remaining == 0.0
-
-        wall_deadline = token.deadline if token.respond_to?(:deadline)
-        wall_deadline && Time.now >= wall_deadline
-      end
-
-      def report_agent_event_callback_error(
-        callback_error,
-        event:,
-        invocation_id:,
-        callback_error_policy:
-      )
-        _report_stream_callback_error(
-          callback_error,
-          event: event,
-          invocation_id: invocation_id,
-          callback_error_policy: callback_error_policy
+      def approve_async(execution_id, approval_request_id:, approved: true, config: {})
+        execution_coordinator.resume(
+          execution_id,
+          approval_request_id: approval_request_id,
+          approved: approved,
+          config: config
         )
       end
 
-      def _register_tool_invocation_session(
-        event_loop,
-        runtime,
-        child,
-        session
-      )
-        completion = Phronomy::Task.deferred(
-          name: "tool-session:#{child.id}"
-        )
-        completion.on_complete do |_result, error|
-          next unless error
+      private
 
-          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}
-            )
-          )
-        end
-        event_loop.register(session, completion: completion)
+      def execution_coordinator
+        @execution_coordinator ||= Agent::ExecutionCoordinator.new(self)
       end
 
-      def _start_approval_resume(
-        result_task,
-        invocation,
-        approved:,
-        config:
-      )
-        invocation.merge_config!(config)
-        invocation.begin_approval_resume!(approved: approved)
-        runtime = Phronomy::Runtime.instance
-        event_loop = runtime.event_loop
-        source_task = Phronomy::Task.deferred(
-          name: "#{result_task.name}-source"
-        )
-        parent_session =
-          Agent::AgentInvocationSessionBuilder.build_for_resume(
-            agent_invocation: invocation,
-            resume_event: :resume,
-            resume_phase: :suspended,
-            runtime: runtime
-          )
-        listener = invocation.event_listener
-        mode = invocation.mode
-        callback_error_policy =
-          Phronomy.configuration.stream_callback_error_policy
-
-        source_task.on_complete do |completed_invocation, error|
-          invocation_result = completed_invocation || parent_session.context
-          _handle_agent_completion(
-            result_task: result_task,
-            invocation: invocation_result,
-            error: error,
-            mode: mode,
-            listener: listener,
-            event_loop: event_loop,
-            callback_error_policy: callback_error_policy
-          )
-        end
-
-        event_loop.register(
-          parent_session,
-          completion: source_task
-        )
-
-        invocation.tool_invocations.each do |child|
-          child_session =
-            if child.awaiting_approval?
-              Agent::ToolInvocationSessionBuilder.build_for_resume(
-                tool_invocation: child,
-                resume_event: approved ? :approve : :reject,
-                resume_phase: :awaiting_approval,
-                runtime: runtime
-              )
-            elsif !approved && child.authorized?
-              Agent::ToolInvocationSessionBuilder.build_for_resume(
-                tool_invocation: child,
-                resume_event: :cancel,
-                resume_phase: :authorized,
-                runtime: runtime
-              )
-            end
-          if child_session
-            _register_tool_invocation_session(
-              event_loop,
-              runtime,
-              child,
-              child_session
-            )
-          end
+      def resolve_event_listener(keyword_listener, block_listener)
+        if keyword_listener && block_listener
+          raise ArgumentError, "Provide either on_event: or a block, not both"
         end
+        keyword_listener || block_listener
       end
     end
   end