phronomy 0.9.0 → 0.10.0

data/lib/phronomy/agent/concerns/suspendable.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "securerandom"
+
 module Phronomy
   module Agent
     module Concerns
@@ -47,6 +49,23 @@ module Phronomy
           @scope_policy = policy
         end
 
+        # Sets the idempotency store used to guard against duplicate resumes.
+        #
+        # The store must respond to:
+        # - +consumed?(checkpoint_id)+ ⇒ Boolean
+        # - +consume!(checkpoint_id)+  ⇒ void; raises {Phronomy::CheckpointAlreadyResumedError} on duplicate
+        #
+        # Defaults to a per-instance {Phronomy::Agent::CheckpointStore} (in-memory, not thread-safe).
+        # Assign a shared persistent store when resuming across processes (e.g. Redis-backed).
+        # Custom stores are responsible for ensuring thread-safety if shared across threads.
+        #
+        # @param store [#consumed?, #consume!]
+        # @return [void]
+        # @api public
+        def checkpoint_store=(store)
+          @checkpoint_store = store
+        end
+
         # Resumes a previously suspended invocation from a {Phronomy::Agent::Checkpoint}.
         #
         # This method reconstructs the conversation state captured at suspension
@@ -59,9 +78,14 @@ module Phronomy
         #   to inject a denial message and let the LLM handle it gracefully
         # @param config     [Hash] same runtime options as #invoke
         # @return [Hash] +{ output: String, suspended: false, messages: Array, usage: Phronomy::TokenUsage }+
+        #   or +{ output: nil, suspended: true, checkpoint: Phronomy::Agent::Checkpoint, messages: Array }+
+        #   when a second approval-required tool is encountered during continuation
         # @raise [Phronomy::GuardrailError] when an output guardrail rejects the value
+        # @raise [Phronomy::CheckpointAlreadyResumedError] when the checkpoint has already been consumed
         # @api private
         def resume(checkpoint, approved:, config: {})
+          # Guard against duplicate resumes using the idempotency store.
+          _checkpoint_store.consume!(checkpoint.checkpoint_id)
           # Build a fresh chat with all tools registered.
           chat = build_chat
 
@@ -91,8 +115,30 @@ module Phronomy
             tool_call_id: checkpoint.pending_tool_call_id
           )
 
-          # Continue the React loop.
-          response = chat.complete
+          # Re-register the suspension hook so that any further requires_approval
+          # tools encountered during continuation are intercepted rather than
+          # executed without approval (cascading / chained approval scenario).
+          _register_suspension_hook!(chat)
+
+          # Continue the LLM loop. Rescue SuspendSignal so that a second
+          # approval-required tool produces a new checkpoint instead of running
+          # without consent.
+          begin
+            response = chat.complete
+          rescue SuspendSignal => signal
+            new_checkpoint = Checkpoint.new(
+              checkpoint_id: SecureRandom.uuid,
+              agent_class: self.class.name,
+              requested_at: Time.now.utc,
+              thread_id: checkpoint.thread_id,
+              original_input: checkpoint.original_input,
+              messages: chat.messages.dup,
+              pending_tool_name: signal.tool_name,
+              pending_tool_args: signal.args,
+              pending_tool_call_id: signal.tool_call_id
+            )
+            return {output: nil, suspended: true, checkpoint: new_checkpoint, messages: chat.messages}
+          end
 
           output = response.content
           usage = Phronomy::TokenUsage.from_tokens(response.tokens)
@@ -129,6 +175,15 @@ module Phronomy
             end
           end
         end
+
+        # Returns the checkpoint idempotency store for this instance, lazily
+        # initialising a default in-memory {Phronomy::Agent::CheckpointStore}.
+        #
+        # @return [#consumed?, #consume!]
+        # @api private
+        def _checkpoint_store
+          @checkpoint_store ||= CheckpointStore.new
+        end
       end
     end
   end

data/lib/phronomy/configuration.rb

@@ -33,6 +33,18 @@ module Phronomy
     # @see Phronomy::EventLoop
     attr_accessor :event_loop
 
+    # When true, agent LLM calls use {Phronomy::MultiAgent::ParallelToolChat}
+    # for concurrent tool dispatch within a single agent turn.
+    # Defaults to false.
+    #
+    # Previously, this was automatically enabled when +event_loop+ was true.
+    # As of Phase 3, +parallel_tool_execution+ is a separate setting that must
+    # be explicitly enabled.
+    # @example
+    #   Phronomy.configure { |c| c.parallel_tool_execution = true }
+    # @return [Boolean]
+    attr_accessor :parallel_tool_execution
+
     # When true, user input and LLM output are recorded in trace spans.
     # Defaults to false; set to true only in environments where PII capture is acceptable.
     # Set to false in privacy-sensitive environments to prevent PII from reaching
@@ -186,6 +198,7 @@ module Phronomy
       @tracer = Phronomy::Tracing::NullTracer.new
       @trace_pii = false
       @event_loop = false
+      @parallel_tool_execution = false
       @event_loop_stop_grace_seconds = 5
       @llm_adapter = Phronomy::LLMAdapter::RubyLLM.new
       @backpressure = :wait

data/lib/phronomy/event_loop.rb

@@ -129,7 +129,7 @@ module Phronomy
     # (WorkflowContext) once the workflow finishes or halts. If an error occurred,
     # the popped value will be an Exception — callers are responsible for re-raising it.
     #
-    # @param fsm_session [Phronomy::Agent::Lifecycle::FSMSession]
+    # @param fsm_session [Phronomy::Workflow::FSMSession]
     # @return [Phronomy::Concurrency::AsyncQueue] resolves to final/halted context, or an Exception
     # @api private
     def register(fsm_session)
@@ -150,23 +150,6 @@ module Phronomy
       completion_queue
     end
 
-    # Enqueues an {AgentFSM} as a fire-and-forget child session.
-    #
-    # Unlike {#register}, this method:
-    # - Is safe to call from the EventLoop thread (entry actions).
-    # - Does NOT block — no completion queue is created.
-    # - Delegates `:finished`/`:error` cleanup to the EventLoop via posted events.
-    #
-    # @param agent_fsm [Phronomy::Agent::FSM]
-    # @return [nil]
-    # @api private
-    def enqueue_child(agent_fsm)
-      @queue.push([Event.new(type: :start, target_id: agent_fsm.id,
-        payload: {session: agent_fsm, completion: nil}),
-        Process.clock_gettime(Process::CLOCK_MONOTONIC, :nanosecond)])
-      nil
-    end
-
     # Posts an event to the loop. Safe to call from any thread (including IO threads).
     # The current monotonic clock time is recorded so that the EventLoop can
     # measure the dispatch lag when it dequeues the event.

data/lib/phronomy/task/mapped_backend.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require "timeout"
+
+module Phronomy
+  class Task
+    # Backend for Tasks created by {Task#map}.
+    #
+    # A mapped task's lifecycle is driven entirely by the +on_complete+
+    # callback of its source task — it never spawns a thread of its own.
+    # +MappedBackend+ transitions the owning task to +:running+ immediately
+    # on initialization so that +FSMSession+ treats it as an in-progress
+    # async action.  Completion (or failure) is triggered externally via
+    # {Task#transition!} from the +on_complete+ callback registered by
+    # {Task#map}.
+    #
+    # +await+ and +join+ block until {#unblock} is called, which {Task#map}
+    # arranges by registering a second +on_complete+ callback on the *mapped*
+    # task itself after the transform callback has been registered.
+    #
+    # @api private
+    class MappedBackend < Backend
+      def initialize(task:, &)
+        super
+        @done_queue = Queue.new
+        task.transition!(:running)
+      end
+
+      # Unblocks +await+ / +join+.  Called by {Task#map} after the mapped task
+      # reaches a terminal state.
+      # @api private
+      def unblock(value, error)
+        @done_queue.push([value, error])
+      end
+
+      # Blocks until the mapped task reaches a terminal state.
+      # @return [Object] the mapped value
+      # @raise [Exception] if the source task or the map block raised an error
+      # @api private
+      def await
+        value, error = @done_queue.pop
+        raise error if error
+
+        value
+      end
+
+      # Returns +false+ — a mapped task has no independent thread to kill.
+      # @return [Boolean]
+      # @api private
+      def alive?
+        false
+      end
+
+      # No-op — mapped tasks carry no independent thread to cancel.
+      # @return [self]
+      # @api private
+      def cancel!
+        self
+      end
+
+      # Blocks until the mapped task completes, with an optional timeout.
+      # @param limit [Numeric, nil]
+      # @return [Object, nil] +nil+ on timeout
+      # @api private
+      def join(limit = nil)
+        if limit.nil?
+          await
+        else
+          begin
+            Timeout.timeout(limit) { await }
+          rescue Timeout::Error
+            nil
+          end
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/task.rb

@@ -4,6 +4,7 @@ require_relative "task/backend"
 require_relative "task/thread_backend"
 require_relative "task/immediate_backend"
 require_relative "task/fiber_backend"
+require_relative "task/mapped_backend"
 
 module Phronomy
   # A single unit of concurrent work.
@@ -195,6 +196,58 @@ module Phronomy
       self
     end
 
+    # Returns a new {Task} whose completed value is the result of applying
+    # +block+ to this task's completed value.
+    #
+    # If this task fails or is cancelled, the mapped task also fails/is
+    # cancelled with the same error.  The block is never called in error cases.
+    #
+    # The primary use-case is transforming an agent result into a
+    # {WorkflowContext} so that a Workflow entry action can return a Task
+    # whose value is picked up by {Workflow::FSMSession} via the existing
+    # +:action_completed+ path:
+    #
+    # @example Returning agent output into a Workflow state field
+    #   entry :translate, ->(ctx) {
+    #     TranslationAgent.new.invoke_async(ctx.query).map do |result|
+    #       ctx.merge(answer: result[:output])   # returns WorkflowContext
+    #     end
+    #   }
+    #
+    # @yield  [value] the completed value of this task
+    # @yieldreturn [Object] the value for the mapped task
+    # @return [Task] a new task that completes when this task does
+    # @api public
+    def map(&block)
+      # MappedBackend drives the task lifecycle entirely via on_complete;
+      # it never spawns a thread of its own.
+      mapped = self.class.spawn(
+        name: "#{@name}-mapped",
+        parent: @parent,
+        backend_class: MappedBackend
+      ) {}
+
+      on_complete do |value, error|
+        mapped_value = nil
+        mapped_error = error
+        unless error
+          begin
+            mapped_value = block.call(value)
+          rescue => e
+            mapped_error = e
+          end
+        end
+        if mapped_error
+          mapped.transition!(:failed, error: mapped_error)
+        else
+          mapped.transition!(:completed, value: mapped_value)
+        end
+        # Unblock mapped.await / mapped.join after the terminal transition.
+        mapped.backend.unblock(mapped_value, mapped_error)
+      end
+      mapped
+    end
+
     # Returns +true+ once the task has finished (success, error, or cancellation).
     # @return [Boolean]
     # @api private

data/lib/phronomy/tools/agent.rb

@@ -3,8 +3,7 @@
 module Phronomy
   module Tools
     # Wraps a Phronomy::Agent::Base subclass as a callable tool so that a parent
-    # ReactAgent (or any agent that supports tools) can delegate sub-tasks to a
-    # fully-capable agent.
+    # agent can delegate sub-tasks to a fully-capable sub-agent.
     #
     # Use Agent.from_agent to generate a concrete tool class.  The generated
     # class is anonymous; assign it to a constant when you need a stable name.
@@ -16,7 +15,7 @@ module Phronomy
     #     description: "Summarizes a long text and returns a brief summary"
     #   )
     #
-    #   class OrchestratorAgent < Phronomy::Agent::ReactAgent
+    #   class OrchestratorAgent < Phronomy::Agent::Base
     #     model "openai/gpt-4o-mini"
     #     instructions "You are an orchestrator that delegates to specialist agents."
     #     tools SummarizerTool

data/lib/phronomy/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Phronomy
-  VERSION = "0.9.0"
+  VERSION = "0.10.0"
 end

data/lib/phronomy/workflow/fsm_session.rb

@@ -0,0 +1,249 @@
+# frozen_string_literal: true
+
+module Phronomy
+  class Workflow
+    # 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