phronomy 0.9.0 → 0.9.1

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.9.1"
 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

data/lib/phronomy/workflow/phase_machine_builder.rb

@@ -0,0 +1,247 @@
+# frozen_string_literal: true
+
+require "state_machines"
+
+module Phronomy
+  class Workflow
+    # Builds the anonymous state-machine Class used by {WorkflowRunner} to track
+    # workflow phase transitions.
+    #
+    # Extracted from {WorkflowRunner#build_phase_machine_class} to reduce the
+    # span of WorkflowRunner's initializer and to give the FSM construction
+    # logic an explicit, testable home.
+    #
+    # Call {#build} to obtain the generated +Class+. The returned class responds
+    # to +#context+ / +#context=+ and +#async_pending+ / +#async_pending=+, and
+    # has a +state_machine :phase+ definition with all registered transitions and
+    # callbacks.
+    #
+    # @api private
+    class PhaseMachineBuilder
+      # @param entry_point      [Symbol]  initial state for the phase machine
+      # @param declared_states  [Array<Symbol>]  all states declared in the workflow
+      # @param wait_state_names [Array<Symbol>]  states that wait for external events
+      # @param external_events  [Hash{Symbol => Array<Hash>}]
+      #   +{ event_name => [{from:, to:, guard:}, ...] }+
+      # @param entry_actions    [Hash{Symbol => Array<#call>}]
+      #   +{ state_name => [callable, ...] }+
+      # @param action_timeouts  [Hash{Symbol => Numeric}]
+      #   +{ state_name => seconds }+
+      # @param auto_transitions [Array<Hash>]
+      #   +[{ from:, to:, guard: }, ...]+ — all auto-fire transitions
+      # @param exit_actions     [Hash{Symbol => Array<#call>}]
+      #   +{ state_name => [callable, ...] }+
+      # @api private
+      def initialize(
+        entry_point:,
+        declared_states:,
+        wait_state_names:,
+        external_events:,
+        entry_actions:,
+        action_timeouts:,
+        auto_transitions:,
+        exit_actions:
+      )
+        @entry_point = entry_point
+        @declared_states = declared_states
+        @wait_state_names = wait_state_names
+        @external_events = external_events
+        @entry_actions = entry_actions
+        @action_timeouts = action_timeouts
+        @auto_transitions = auto_transitions
+        @exit_actions = exit_actions
+      end
+
+      # Constructs and returns the anonymous phase-machine Class.
+      #
+      # @return [Class] an anonymous class with a +state_machine :phase+ definition
+      # @raise [ArgumentError] if state_machines raises during class construction
+      # @api private
+      def build
+        entry = @entry_point
+        all_states = (@declared_states + @wait_state_names + [:__end__]).uniq
+        auto_trans = @auto_transitions
+        ext_events = @external_events
+        entry_acts = @entry_actions
+        exit_acts = @exit_actions
+        act_timeouts = @action_timeouts
+        build_cb = method(:build_entry_callback)
+
+        Class.new do
+          # Holds the current WorkflowContext so guards and callbacks can read it.
+          attr_accessor :context
+
+          # Set to true by an entry action that returned an awaitable Task.
+          # When true, FSMSession skips the automatic advance_or_halt step and
+          # waits for the async worker thread to post a state_completed event back.
+          attr_accessor :async_pending
+
+          state_machine :phase, initial: entry do
+            all_states.each { |s| state s }
+
+            # Auto-fire transitions: all auto transitions unified under :state_completed.
+            # Includes unguarded (unconditional) and guarded (conditional) transitions.
+            # Declaration order is preserved; guards are evaluated before unguarded fallbacks.
+            event :state_completed do
+              auto_trans.each do |t|
+                if t[:guard]
+                  guard_proc = t[:guard]
+                  transition t[:from] => t[:to], :if => ->(m) { guard_proc.call(m.context) }
+                else
+                  transition t[:from] => t[:to]
+                end
+              end
+            end
+
+            # External events: human-in-the-loop triggers from wait states.
+            ext_events.each do |ev_name, transitions|
+              event ev_name do
+                transitions.each do |t|
+                  if t[:guard]
+                    guard_proc = t[:guard]
+                    transition t[:from] => t[:to], :if => ->(m) { guard_proc.call(m.context) }
+                  else
+                    transition t[:from] => t[:to]
+                  end
+                end
+              end
+            end
+
+            # Entry callbacks: fire after_transition into each state.
+            #    Each callable is registered as a separate callback; state_machines
+            #    accumulates them and fires in declaration order.
+            #    If the callable returns a WorkflowContext (e.g. via s.merge(...)),
+            #    the returned context replaces the current one on the tracker.
+            entry_acts.each do |state_name, callables|
+              callables.each do |callable|
+                cb = build_cb.call(callable, state_name, act_timeouts[state_name])
+                after_transition to: state_name, &cb
+              end
+            end
+
+            # Exit callbacks: fire before_transition out of each state.
+            #    Each callable is registered as a separate callback; state_machines
+            #    accumulates them and fires in declaration order.
+            exit_acts.each do |state_name, callables|
+              callables.each do |callable|
+                before_transition from: state_name do |machine|
+                  callable.call(machine.context)
+                end
+              end
+            end
+          end
+        end
+      rescue => e
+        raise ArgumentError, "Failed to build phase machine: #{e.message}"
+      end
+
+      private
+
+      # Returns a proc suitable for use as an +after_transition+ callback.
+      #
+      # The returned proc accepts a single argument (the phase machine instance),
+      # invokes the entry action callable with the current context, then delegates
+      # the result to {#handle_entry_action_result}.  Capturing this in the
+      # builder's scope lets the anonymous +Class.new+ block stay slim.
+      #
+      # @param callable     [#call]  the entry action
+      # @param state_name   [Symbol] name of the target state (for error messages)
+      # @param timeout_secs [Numeric, nil] seconds before ActionTimeoutError
+      # @return [Proc]
+      # @api private
+      def build_entry_callback(callable, state_name, timeout_secs)
+        handle = method(:handle_entry_action_result)
+        ->(machine) {
+          result = callable.call(machine.context)
+          handle.call(machine, result, state_name, timeout_secs)
+        }
+      end
+
+      # Dispatches the return value of an entry action callable.
+      #
+      # - +Phronomy::Task+            → async or blocking task handling
+      # - +Phronomy::WorkflowContext+ → replaces the machine's context directly
+      # - anything else               → ignored
+      #
+      # @param machine       [Object]           phase machine instance
+      # @param result        [Object]           return value of the entry callable
+      # @param state_name    [Symbol]           name of the entered state
+      # @param timeout_secs  [Numeric, nil]     optional timeout in seconds
+      # @api private
+      def handle_entry_action_result(machine, result, state_name, timeout_secs)
+        if result.is_a?(Phronomy::Task)
+          if Phronomy.configuration.event_loop
+            dispatch_task_in_event_loop(machine, result, state_name, timeout_secs)
+          else
+            await_task_blocking(machine, result, state_name, timeout_secs)
+          end
+        elsif result.is_a?(Phronomy::WorkflowContext)
+          machine.context = result
+        end
+      end
+
+      # Handles a +Phronomy::Task+ return value in EventLoop mode.
+      #
+      # Marks the machine as async-pending and spawns a cooperative background
+      # task that awaits the result, then posts the appropriate event back to
+      # the EventLoop.  +FSMSession+ will skip the automatic +advance_or_halt+
+      # step while +async_pending+ is true.
+      #
+      # @param machine       [Object]       phase machine instance
+      # @param result        [Phronomy::Task]
+      # @param state_name    [Symbol]
+      # @param timeout_secs  [Numeric, nil]
+      # @api private
+      def dispatch_task_in_event_loop(machine, result, state_name, timeout_secs)
+        machine.async_pending = true
+        thread_id = machine.context.thread_id
+        Phronomy::Runtime.instance.spawn(name: "wf-await-#{thread_id}") do
+          enforce_timeout!(result, state_name, timeout_secs)
+          task_result = result.await
+          ev = if task_result.is_a?(Phronomy::WorkflowContext)
+            Phronomy::Event.new(type: :action_completed, target_id: thread_id, payload: task_result)
+          else
+            Phronomy::Event.new(type: :state_completed, target_id: thread_id, payload: nil)
+          end
+          Phronomy::EventLoop.instance.post(ev)
+        rescue => e
+          Phronomy::EventLoop.instance.post(
+            Phronomy::Event.new(type: :error, target_id: thread_id, payload: e)
+          )
+        end
+      end
+
+      # Handles a +Phronomy::Task+ return value in non-EventLoop mode.
+      #
+      # Blocks the current execution context until the task completes or the
+      # optional timeout elapses.
+      #
+      # @param machine       [Object]       phase machine instance
+      # @param result        [Phronomy::Task]
+      # @param state_name    [Symbol]
+      # @param timeout_secs  [Numeric, nil]
+      # @api private
+      def await_task_blocking(machine, result, state_name, timeout_secs)
+        enforce_timeout!(result, state_name, timeout_secs)
+        task_result = result.await
+        machine.context = task_result if task_result.is_a?(Phronomy::WorkflowContext)
+      end
+
+      # Raises +ActionTimeoutError+ if the task does not complete within
+      # +timeout_secs+.  No-op when +timeout_secs+ is +nil+.
+      #
+      # @param result       [Phronomy::Task]
+      # @param state_name   [Symbol]
+      # @param timeout_secs [Numeric, nil]
+      # @api private
+      def enforce_timeout!(result, state_name, timeout_secs)
+        return unless timeout_secs
+        return unless result.join(timeout_secs).nil?
+
+        result.cancel!
+        raise Phronomy::ActionTimeoutError,
+          "Action in state #{state_name.inspect} timed out after #{timeout_secs}s"
+      end
+    end
+  end
+end

data/lib/phronomy/workflow_runner.rb

@@ -56,7 +56,7 @@ module Phronomy
       @wait_state_names = wait_state_names
       @state_store = state_store
       @action_timeouts = action_timeouts   # { state_name => seconds }
-      @phase_machine_class = Agent::Lifecycle::PhaseMachineBuilder.new(
+      @phase_machine_class = Workflow::PhaseMachineBuilder.new(
         entry_point: @entry_point,
         declared_states: @declared_states,
         wait_state_names: @wait_state_names,
@@ -169,7 +169,7 @@ module Phronomy
 
     # Builds an FSMSession for the given context. Used in EventLoop mode.
     def build_session_for(context:, recursion_limit:, resume_event: nil, resume_phase: nil)
-      Phronomy::Agent::Lifecycle::FSMSession.new(
+      Phronomy::Workflow::FSMSession.new(
         id: context.thread_id,
         context: context,
         entry_point: @entry_point,

data/lib/phronomy.rb

@@ -12,8 +12,6 @@ loader.inflector.inflect("ruby_llm_embeddings" => "RubyLLMEmbeddings")
 loader.inflector.inflect("rag" => "RAG")
 # FSMSession: Zeitwerk would infer "FsmSession" — override to "FSMSession".
 loader.inflector.inflect("fsm_session" => "FSMSession")
-# AgentFSM: Zeitwerk would infer "Fsm" — override to "FSM".
-loader.inflector.inflect("fsm" => "FSM")
 # LLMAdapter: Zeitwerk would infer "LlmAdapter" — override to "LLMAdapter".
 loader.inflector.inflect("llm_adapter" => "LLMAdapter")
 # LLMAdapter::RubyLLM: "ruby_llm" maps to "RubyLLM" (not "RubyLlm").
@@ -98,6 +96,14 @@ module Phronomy
     end
   end
 
+  # Raised when {Agent::Base#resume} (or the class-level equivalent) is called
+  # with a {Agent::Checkpoint} whose +checkpoint_id+ has already been consumed
+  # by a previous +resume+ call on the same store.
+  #
+  # This protects against duplicate resume executions caused by webhook retries
+  # or queue message redelivery.
+  class CheckpointAlreadyResumedError < Error; end
+
   # Raised when an operation is submitted to a {BlockingAdapterPool} that has
   # already been shut down via {BlockingAdapterPool#shutdown}.
   class PoolShutdownError < Error; end

data/scripts/api_snapshot.rb

@@ -30,7 +30,6 @@ PUBLIC_API_ENTRIES = [
   Phronomy::Runnable,
   Phronomy::Agent::Context::Instruction::PromptTemplate,
   # Beta
-  Phronomy::Agent::ReactAgent,
   Phronomy::MultiAgent::Orchestrator,
   Phronomy::MultiAgent::TeamCoordinator,
   Phronomy::Guardrail::InputGuardrail,

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: phronomy
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 0.9.1
 platform: ruby
 authors:
 - Raizo T.C.S
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-06-01 00:00:00.000000000 Z
+date: 2026-06-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ruby_llm
@@ -106,6 +106,7 @@ files:
 - lib/phronomy/agent/base.rb
 - lib/phronomy/agent/before_completion_context.rb
 - lib/phronomy/agent/checkpoint.rb
+- lib/phronomy/agent/checkpoint_store.rb
 - lib/phronomy/agent/concerns/before_completion.rb
 - lib/phronomy/agent/concerns/error_translation.rb
 - lib/phronomy/agent/concerns/guardrailable.rb
@@ -117,11 +118,6 @@ files:
 - lib/phronomy/agent/context/knowledge/base.rb
 - lib/phronomy/agent/context/knowledge/entity_knowledge.rb
 - lib/phronomy/agent/context/knowledge/static_knowledge.rb
-- lib/phronomy/agent/fsm.rb
-- lib/phronomy/agent/invocation_pipeline.rb
-- lib/phronomy/agent/lifecycle/fsm_session.rb
-- lib/phronomy/agent/lifecycle/phase_machine_builder.rb
-- lib/phronomy/agent/react_agent.rb
 - lib/phronomy/agent/runner.rb
 - lib/phronomy/agent/shared_state.rb
 - lib/phronomy/agent/suspend_signal.rb
@@ -226,6 +222,8 @@ files:
 - lib/phronomy/vector_store/splitter/recursive_splitter.rb
 - lib/phronomy/version.rb
 - lib/phronomy/workflow.rb
+- lib/phronomy/workflow/fsm_session.rb
+- lib/phronomy/workflow/phase_machine_builder.rb
 - lib/phronomy/workflow_context.rb
 - lib/phronomy/workflow_runner.rb
 - scripts/api_snapshot.rb