phronomy 0.7.0 → 0.8.0

data/lib/phronomy/agent/fsm.rb

@@ -8,21 +8,21 @@ module Phronomy
     #
     # +AgentFSM+ implements the minimal interface expected by {Phronomy::EventLoop}
     # (+#id+, +#start+, +#handle+) so it can be managed alongside
-    # {Phronomy::FSMSession} instances.  It is *not* a traditional finite-state
+    # {Phronomy::Agent::Lifecycle::FSMSession} instances.  It is *not* a traditional finite-state
     # machine; the name reflects its role in the EventLoop rather than internal
     # state transitions.
     #
     # == Execution model
     #
     # {#start} is called by the EventLoop on the +:start+ event.  It immediately
-    # returns after spawning a background IO thread that runs the agent's full
+    # returns after spawning a {Phronomy::Task} that runs the agent's full
     # invocation pipeline (via +_invoke_impl+).  The EventLoop thread is never
     # blocked by agent execution.
     #
-    # Inside the IO thread, the +:phronomy_agent_parallel_tools+ thread-local
-    # flag is set to +true+ so that {Agent::Base#build_chat} returns a
-    # {ParallelToolChat} instance, enabling concurrent tool dispatch when the LLM
-    # returns multiple tool calls in one response.
+    # Inside the task, {Agent::Base#build_chat} returns a
+    # {ParallelToolChat} instance when EventLoop mode is enabled, allowing
+    # concurrent tool dispatch when the LLM returns multiple tool calls in one
+    # response.
     #
     # == Completion events
     #
@@ -72,40 +72,30 @@ module Phronomy
       #                                           auto-generated when nil
       # @param config    [Hash]                   invocation config forwarded to
       #                                           +_invoke_impl+
-      # @param parent_id    [String, nil]  EventLoop id of the parent
-      #                                     FSMSession; when set, a
-      #                                     +:child_completed+ event is posted
-      #                                     on completion
-      # @param result_writer [Proc, nil]   optional callable invoked with the
-      #                                     result hash <b>before</b>
-      #                                     +:child_completed+ is posted.
-      #                                     Use this to write the agent output
-      #                                     back into the parent WorkflowContext.
-      #                                     Thread::Queue provides the
-      #                                     happens-before guarantee.
+      # @param parent_id [String, nil]  EventLoop id of the parent FSMSession;
+      #                                  when set, a +:child_completed+ event
+      #                                  is posted on completion.  The result
+      #                                  is delivered exclusively as the event
+      #                                  payload — no cross-thread writes to the
+      #                                  parent WorkflowContext are performed.
       #
-      # @example Writing result into context
-      #   entry :run_agent, ->(ctx) {
-      #     MyAgent.new.run_as_child(ctx.query, ctx: ctx) { |r| ctx.answer = r[:output] }
-      #   }
       # @api private
-      def initialize(agent:, input:, messages: [], thread_id: nil, config: {}, parent_id: nil, result_writer: nil)
+      def initialize(agent:, input:, messages: [], thread_id: nil, config: {}, parent_id: nil)
         @agent = agent
         @input = input
         @messages = Array(messages).dup
         @thread_id = thread_id || SecureRandom.uuid
         @config = config
         @parent_id = parent_id
-        @result_writer = result_writer
         @id = @thread_id
         @current_phase = :idle
       end
 
       # Called by {EventLoop} on the +:start+ event.
-      # Transitions to +:running+ and spawns the agent IO thread.
+      # Transitions to +:running+ and spawns the agent task.
       def start
         @current_phase = :running
-        spawn_agent_thread
+        spawn_agent_task
       end
 
       # Called by {EventLoop} for external events dispatched to this id.
@@ -117,10 +107,10 @@ module Phronomy
 
       private
 
-      # Spawns the background IO thread that runs the agent invocation.
-      # Captures all instance variables by value so the thread closure is
+      # Spawns a {Phronomy::Task} that runs the agent invocation pipeline.
+      # Captures all instance variables by value so the task closure is
       # safe even if the FSM object is modified (though it is not in practice).
-      def spawn_agent_thread
+      def spawn_agent_task
         agent = @agent
         input = @input
         messages = @messages
@@ -128,51 +118,38 @@ module Phronomy
         config = @config
         fsm_id = @id
         parent_id = @parent_id
-        result_writer = @result_writer
 
-        Thread.new do
-          # Enable parallel tool dispatch inside this IO thread.
-          Thread.current[:phronomy_agent_parallel_tools] = true
-          # Forward the concurrency cap to ParallelToolChat.
-          Thread.current[:phronomy_max_parallel_tools] =
-            agent.class.respond_to?(:max_parallel_tools) ? agent.class.max_parallel_tools : 10
-
-          begin
-            result = agent.send(:_invoke_impl,
-              input,
-              messages: messages,
-              thread_id: thread_id,
-              config: config)
-
-            if parent_id
-              # Let the caller write the result into the context BEFORE the
-              # parent FSMSession advances.  Thread::Queue provides the
-              # happens-before guarantee — no Mutex needed.
-              result_writer&.call(result)
-
-              Phronomy::EventLoop.instance.post(
-                Phronomy::Event.new(type: :child_completed, target_id: parent_id, payload: result)
-              )
-            end
+        Phronomy::Runtime.instance.spawn(name: "agent-fsm:#{fsm_id}") do
+          result = agent.send(:_invoke_impl,
+            input,
+            messages: messages,
+            thread_id: thread_id,
+            config: config)
 
+          if parent_id
+            # Result is delivered exclusively as the :child_completed payload.
+            # The parent Workflow task is the sole owner of WorkflowContext
+            # and applies the result after receiving the event.
             Phronomy::EventLoop.instance.post(
-              Phronomy::Event.new(type: :finished, target_id: fsm_id, payload: result)
+              Phronomy::Event.new(type: :child_completed, target_id: parent_id, payload: result)
             )
-          rescue => e
-            if parent_id
-              Phronomy::EventLoop.instance.post(
-                Phronomy::Event.new(type: :child_failed, target_id: parent_id, payload: e)
-              )
-            end
+          end
 
+          Phronomy::EventLoop.instance.post(
+            Phronomy::Event.new(type: :finished, target_id: fsm_id, payload: result)
+          )
+        rescue => e
+          if parent_id
             Phronomy::EventLoop.instance.post(
-              Phronomy::Event.new(type: :error, target_id: fsm_id, payload: e)
+              Phronomy::Event.new(type: :child_failed, target_id: parent_id, payload: e)
             )
-          ensure
-            # Clear the thread-local context cache for this agent so the IO
-            # thread's cache does not grow unboundedly across invocations.
-            Thread.current[:phronomy_context_version_caches]&.delete(agent.object_id)
           end
+
+          Phronomy::EventLoop.instance.post(
+            Phronomy::Event.new(type: :error, target_id: fsm_id, payload: e)
+          )
+
+          # Context caches are instance variables; no thread-local cleanup needed.
         end
       end
     end

data/lib/phronomy/agent/invocation_pipeline.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    # Encapsulates the core per-invocation LLM round-trip for {Agent::Base}.
+    #
+    # {Agent::Base#invoke_once} delegates the body of each LLM turn to this
+    # class, keeping the caller to a thin setup + trace frame (span≈2).
+    # The pipeline executes inside the agent's binding via +instance_exec+
+    # so that private concern methods (guardrails, hooks, cancellation) remain
+    # encapsulated in their original modules while the orchestration logic lives
+    # here.
+    #
+    # @api private
+    class InvocationPipeline
+      # @param agent [Agent::Base] the agent instance driving this invocation
+      # @api private
+      def initialize(agent)
+        @agent = agent
+      end
+
+      # Runs one LLM round-trip inside the agent's execution context.
+      #
+      # Calls private {Agent::Base} concern methods (guardrails, hooks,
+      # cancellation) via +instance_exec+ so that their encapsulation is
+      # preserved, then routes the LLM request through the configured adapter.
+      #
+      # @param input      [String, Hash] the user input for this turn
+      # @param messages   [Array]        prior conversation messages
+      # @param thread_id  [String, nil]  persistence thread identifier
+      # @param config     [Hash]         per-invocation options
+      # @return [Array(Hash, Phronomy::TokenUsage, nil)]
+      #   A two-element array: the result hash and the token usage (or nil on
+      #   suspension).
+      # @api private
+      def run(input, messages:, thread_id:, config:)
+        @agent.instance_exec(input, messages, thread_id, config) do |inp, msgs, tid, cfg|
+          # Run input guardrails before touching the LLM.
+          run_input_guardrails!(inp)
+
+          user_message = extract_message(inp)
+          chat = build_chat
+
+          # Assemble context (system prompt + history). Override #build_context to
+          # inject custom context editing logic at the Agent subclass level.
+          context = build_context(inp, messages: msgs, thread_id: tid, config: cfg)
+          apply_instructions(chat, context[:system]) if context[:system]
+          context[:messages].each { |msg| chat.messages << msg }
+
+          # Run before_completion hooks (global → class → instance) before the LLM call.
+          run_before_completion_hooks!(chat, cfg)
+
+          # Register suspension hook for approval-required tools (no-op when a
+          # synchronous on_approval_required handler is already registered).
+          _register_suspension_hook!(chat)
+
+          # Check for cancellation immediately before the LLM call.
+          check_cancellation!(cfg, "invocation cancelled before LLM call")
+
+          # Forward the cancellation token to ParallelToolChat explicitly
+          # via the chat instance so that tool dispatch batches can observe
+          # cancellation without needing Thread.current.
+          chat.cancellation_token = cfg[:cancellation_token] if chat.respond_to?(:cancellation_token=)
+
+          begin
+            # Route the LLM call through the configured LLMAdapter so that the
+            # blocking HTTP request runs inside BlockingAdapterPool and the
+            # adapter can be swapped without changing agent code.
+            adapter = Phronomy.configuration.llm_adapter
+            response = adapter.complete_async(chat, user_message, config: cfg).await
+          rescue SuspendSignal => signal
+            checkpoint = Checkpoint.new(
+              thread_id: tid,
+              original_input: inp,
+              messages: chat.messages.dup,
+              pending_tool_name: signal.tool_name,
+              pending_tool_args: signal.args,
+              pending_tool_call_id: signal.tool_call_id
+            )
+            suspended_result = {output: nil, suspended: true, checkpoint: checkpoint, messages: chat.messages}
+            next [suspended_result, nil]
+          ensure
+            # Clear the chat's cancellation token reference after each LLM call.
+            chat.cancellation_token = nil if chat.respond_to?(:cancellation_token=)
+          end
+
+          output = response.content
+          usage = Phronomy::TokenUsage.from_tokens(response.tokens)
+
+          # Run output guardrails before returning to the caller.
+          run_output_guardrails!(output)
+
+          result = {output: output, messages: chat.messages, usage: usage}
+          [result, usage]
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/agent/lifecycle/fsm_session.rb

@@ -0,0 +1,251 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    module Lifecycle
+      # Event-driven execution wrapper for a single workflow run.
+      #
+      # Created by WorkflowRunner and registered with EventLoop. All public methods
+      # are called from the EventLoop thread — FSMSession is NOT thread-safe and must
+      # not be accessed concurrently from multiple threads.
+      #
+      # == Lifecycle
+      #
+      #   register(session) → EventLoop posts :start → session.start
+      #                                 ↓ (auto-transition present)
+      #                        EventLoop posts :state_completed → session.handle
+      #                                 ↓ (repeat)
+      #                        session posts :finished or :halted
+      #                                 ↓
+      #                        EventLoop pushes ctx to completion_queue → caller unblocks
+      #
+      # == Async IO pattern (EventLoop mode only)
+      #
+      # When a state has no auto-transition and is not a wait_state, but has an
+      # external event registered (e.g. +transition from: :fetching, on: :fetch_done+),
+      # the FSMSession stays registered in the EventLoop and waits for that event.
+      # The entry action is expected to spawn an IO thread that posts the event back:
+      #
+      #   entry :fetching, ->(ctx) {
+      #     Thread.new {
+      #       ctx.result = http.get(ctx.url)
+      #       Phronomy::EventLoop.instance.post(
+      #         Phronomy::Event.new(type: :fetch_done, target_id: ctx.thread_id, payload: nil)
+      #       )
+      #     }
+      #   }
+      #   transition from: :fetching, on: :fetch_done, to: :process
+      class FSMSession
+        FINISH = WorkflowRunner::FINISH
+
+        # @return [String] workflow thread_id (matches WorkflowContext#thread_id)
+        attr_reader :id
+
+        # @param id                  [String]
+        # @param context             [Object]        includes Phronomy::WorkflowContext
+        # @param entry_point         [Symbol]        initial state name
+        # @param entry_actions       [Hash]          { state_name => [callable, ...] }
+        # @param auto_state_set      [Hash]          { state_name => true }
+        # @param declared_states     [Array<Symbol>] all action state names
+        # @param wait_state_names    [Array<Symbol>]
+        # @param external_events     [Hash]          { event_name => [{from:, to:, guard:}] }
+        # @param phase_machine_class [Class]         state_machines-backed phase tracker class
+        # @param recursion_limit     [Integer]
+        # @param action_timeouts     [Hash]          { state_name => seconds }
+        # @param resume_event        [Symbol, nil]   external event to fire when resuming
+        # @param resume_phase        [Symbol, nil]   wait state name to resume from
+        # @api private
+        def initialize(id:, context:, entry_point:, entry_actions:, auto_state_set:,
+          declared_states:, wait_state_names:, external_events:, phase_machine_class:,
+          recursion_limit:, action_timeouts: {}, resume_event: nil, resume_phase: nil)
+          @id = id
+          @ctx = context
+          @entry_point = entry_point
+          @entry_actions = entry_actions
+          @auto_state_set = auto_state_set
+          @declared_states = declared_states
+          @wait_state_names = wait_state_names
+          @external_events = external_events
+          @phase_machine_class = phase_machine_class
+          @recursion_limit = recursion_limit
+          @action_timeouts = action_timeouts
+          @resume_event = resume_event
+          @resume_phase = resume_phase
+          @step = 0
+          @done = false
+          @current_state = nil
+          @tracker = nil
+        end
+
+        # Begins workflow execution. Called by EventLoop on :start event.
+        def start
+          if @resume_event
+            # Resume from wait state: position tracker at the wait state, then fire the
+            # external event. state_machines fires before_transition (exit) and
+            # after_transition (entry) callbacks, so both actions execute here.
+            @current_state = @resume_phase
+            @tracker = build_tracker(@current_state)
+            @tracker.context = @ctx
+            fire_and_advance!(@resume_event)
+          else
+            # Fresh start: state_machines does not fire callbacks on initialization,
+            # so we invoke the entry action for the initial state manually.
+            @current_state = @entry_point
+            @tracker = build_tracker(@current_state)
+            @tracker.context = @ctx
+            (@entry_actions[@current_state] || []).each do |c|
+              result = c.call(@ctx)
+              if result.is_a?(Phronomy::Task)
+                # Awaitable action: spawn a task to await without blocking EventLoop.
+                @tracker.async_pending = true
+                session_id = @id
+                current_state_name = @current_state
+                timeout_secs = @action_timeouts[current_state_name]
+                Phronomy::Runtime.instance.spawn(name: "fsm-await-#{session_id}") do
+                  if timeout_secs
+                    if result.join(timeout_secs).nil?
+                      result.cancel!
+                      raise Phronomy::ActionTimeoutError,
+                        "Action in state #{current_state_name.inspect} timed out after #{timeout_secs}s"
+                    end
+                  end
+                  task_result = result.await
+                  if task_result.is_a?(Phronomy::WorkflowContext)
+                    event_loop.post(Event.new(type: :action_completed, target_id: session_id, payload: task_result))
+                  else
+                    event_loop.post(Event.new(type: :state_completed, target_id: session_id, payload: nil))
+                  end
+                rescue => e
+                  event_loop.post(Event.new(type: :error, target_id: session_id, payload: e))
+                end
+                break # Only one async action at a time per state
+              elsif result.is_a?(Phronomy::WorkflowContext)
+                @ctx = result
+              end
+            end
+            @tracker.context = @ctx
+            advance_or_halt unless @tracker.async_pending
+          end
+        rescue => e
+          finish_with_error(e)
+        end
+
+        # Processes an event dispatched from EventLoop.
+        # Called for :state_completed, :action_completed, and all user-defined external events.
+        #
+        # @param event [Phronomy::Event]
+        # @api private
+        def handle(event)
+          return if @done
+
+          if event.type == :action_completed
+            # An awaitable entry action completed: update context and advance.
+            @ctx = event.payload if event.payload.is_a?(Phronomy::WorkflowContext)
+            @tracker.context = @ctx
+            @tracker.async_pending = false  # Reset flag set by start or fire_and_advance!
+            advance_or_halt
+            return
+          end
+
+          fire_and_advance!(event.type)
+        rescue => e
+          finish_with_error(e)
+        end
+
+        private
+
+        # Fires event_name on the phase tracker, updates @current_state, then
+        # calls advance_or_halt to decide what to do next.
+        def fire_and_advance!(event_name)
+          if @step >= @recursion_limit
+            raise Phronomy::RecursionLimitError,
+              "Recursion limit (#{@recursion_limit}) exceeded"
+          end
+
+          fire_event!(@tracker, event_name, @current_state)
+          @ctx = @tracker.context
+          next_phase = @tracker.phase.to_sym
+          # When next_phase == @current_state, no transition matched → treat as terminal.
+          @current_state = (next_phase == @current_state) ? FINISH : next_phase
+          @step += 1
+
+          # If an entry action returned a Task, the after_transition callback set
+          # async_pending = true and spawned a thread. Skip advance_or_halt — the
+          # background thread will post :action_completed or :state_completed.
+          if @tracker.async_pending
+            @tracker.async_pending = false
+            return
+          end
+
+          advance_or_halt
+        end
+
+        # Determines the next action after the FSM has entered @current_state.
+        def advance_or_halt
+          return finish! if @current_state == FINISH
+
+          if @wait_state_names.include?(@current_state)
+            return halt!
+          end
+
+          if @auto_state_set.key?(@current_state)
+            event_loop.post(Event.new(type: :state_completed, target_id: @id, payload: nil))
+            return
+          end
+
+          if has_external_event_from?(@current_state)
+            # Async IO pattern: the entry action spawned an IO thread that will post
+            # an external event back. Stay registered; do nothing here.
+            return
+          end
+
+          # No transition declared — validate the state is known, then treat as terminal.
+          unless @declared_states.include?(@current_state)
+            raise ArgumentError, "State #{@current_state.inspect} is not defined"
+          end
+
+          finish!
+        end
+
+        def finish!
+          @done = true
+          @ctx.set_graph_metadata(thread_id: @id, phase: :__end__)
+          event_loop.post(Event.new(type: :finished, target_id: @id, payload: @ctx))
+        end
+
+        def halt!
+          @done = true
+          @ctx.set_graph_metadata(thread_id: @id, phase: @current_state)
+          event_loop.post(Event.new(type: :halted, target_id: @id, payload: @ctx))
+        end
+
+        def finish_with_error(err)
+          @done = true
+          event_loop.post(Event.new(type: :error, target_id: @id, payload: err))
+        end
+
+        def fire_event!(tracker, event_name, from_state)
+          return if tracker.send(event_name)
+
+          raise ArgumentError,
+            "Transition from #{from_state.inspect} via event #{event_name.inspect} failed. " \
+            "Ensure at least one guard matches or add a fallback (no-guard) transition."
+        end
+
+        def has_external_event_from?(state)
+          @external_events.any? { |_, transitions| transitions.any? { |t| t[:from] == state } }
+        end
+
+        def build_tracker(from_state)
+          machine = @phase_machine_class.new
+          machine.instance_variable_set(:@phase, from_state.to_s)
+          machine
+        end
+
+        def event_loop
+          Phronomy::EventLoop.instance
+        end
+      end
+    end
+  end
+end