phronomy 0.9.0 → 0.10.0

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
@@ -117,7 +123,8 @@ module Phronomy
   # Raised when a {Phronomy::WorkflowContext} field is mutated from a thread
   # that does not own the context (i.e. not the EventLoop dispatch thread).
   # Only raised in EventLoop mode.  Use +context.merge(...)+ to produce a new
-  # context, or deliver updates as +:child_completed+ event payloads.
+  # context, or deliver updates as +:action_completed+ event payloads
+  # via {Agent::Base#invoke_async} + {Task#map}.
   class WorkflowContextOwnershipError < Error; end
 
   class << self

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.10.0
 platform: ruby
 authors:
 - Raizo T.C.S
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-06-01 00:00:00.000000000 Z
+date: 2026-06-07 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
@@ -193,6 +189,7 @@ files:
 - lib/phronomy/task/backend.rb
 - lib/phronomy/task/fiber_backend.rb
 - lib/phronomy/task/immediate_backend.rb
+- lib/phronomy/task/mapped_backend.rb
 - lib/phronomy/task/thread_backend.rb
 - lib/phronomy/task_group.rb
 - lib/phronomy/testing.rb
@@ -226,6 +223,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

data/lib/phronomy/agent/fsm.rb

@@ -1,157 +0,0 @@
-# frozen_string_literal: true
-
-require "securerandom"
-
-module Phronomy
-  module Agent
-    # EventLoop-registered execution unit for a single agent invocation.
-    #
-    # +AgentFSM+ implements the minimal interface expected by {Phronomy::EventLoop}
-    # (+#id+, +#start+, +#handle+) so it can be managed alongside
-    # {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 {Phronomy::Task} that runs the agent's full
-    # invocation pipeline (via +_invoke_impl+).  The EventLoop thread is never
-    # blocked by agent execution.
-    #
-    # 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
-    #
-    # On *success*:
-    #   - Posts +:finished+ to this FSM's own +#id+ so the EventLoop cleans up
-    #     its registry entry and unblocks any +completion_queue.pop+ caller.
-    #   - When +parent_id+ is set (child-FSM pattern), additionally posts
-    #     +:child_completed+ to +parent_id+, carrying the result hash as the
-    #     event payload.  The parent {FSMSession} must declare an +on:+ transition
-    #     for +:child_completed+ to advance correctly.
-    #
-    # On *error*:
-    #   - Posts +:error+ to this FSM's own +#id+.  The EventLoop propagates the
-    #     exception through the +completion_queue+ so that the original caller of
-    #     +Agent::Base#invoke+ (in EventLoop mode) receives and re-raises it.
-    #
-    # == Standalone usage (blocking caller)
-    #
-    #   Phronomy.configure { |c| c.event_loop = true }
-    #   result = MyAgent.new.invoke("Hello!")   # => { output:, messages:, usage: }
-    #
-    # {Agent::Base#invoke} detects EventLoop mode, creates an +AgentFSM+, registers
-    # it via {EventLoop#register}, and blocks the *calling* thread on the returned
-    # +completion_queue+ until the agent finishes.
-    #
-    # == Child-FSM usage (non-blocking, inside a Workflow)
-    #
-    #   state :run_agent
-    #   entry :run_agent, ->(ctx) { MyAgent.new.run_as_child(ctx.query, ctx: ctx) }
-    #   transition from: :run_agent, on: :child_completed, to: :process_result
-    #
-    # {Agent::Base#run_as_child} creates an +AgentFSM+ with +parent_id+ set to
-    # +ctx.thread_id+, registers it with the EventLoop, and returns immediately.
-    # The parent {FSMSession} waits for the +:child_completed+ event.
-    # @api private
-    class FSM
-      # @return [String] unique identifier used as the EventLoop target_id
-      attr_reader :id
-
-      # @return [Symbol] current internal phase (:idle, :running)
-      attr_reader :current_phase
-
-      # @param agent     [Phronomy::Agent::Base]  agent instance to run
-      # @param input     [String, Hash]           user input passed to +invoke_once+
-      # @param messages  [Array]                  prior conversation history
-      # @param thread_id [String, nil]            conversation thread id;
-      #                                           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.  The result
-      #                                  is delivered exclusively as the event
-      #                                  payload — no cross-thread writes to the
-      #                                  parent WorkflowContext are performed.
-      #
-      # @api private
-      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
-        @id = @thread_id
-        @current_phase = :idle
-      end
-
-      # Called by {EventLoop} on the +:start+ event.
-      # Transitions to +:running+ and spawns the agent task.
-      def start
-        @current_phase = :running
-        spawn_agent_task
-      end
-
-      # Called by {EventLoop} for external events dispatched to this id.
-      # +AgentFSM+ is fully driven by its own IO thread and does not respond
-      # to external events after {#start}.
-      def handle(_event)
-        # No-op: AgentFSM is driven entirely by its IO thread.
-      end
-
-      private
-
-      # 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_task
-        agent = @agent
-        input = @input
-        messages = @messages
-        thread_id = @thread_id
-        config = @config
-        fsm_id = @id
-        parent_id = @parent_id
-
-        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: :child_completed, target_id: parent_id, payload: result)
-            )
-          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: :child_failed, target_id: parent_id, payload: e)
-            )
-          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
-  end
-end

data/lib/phronomy/agent/invocation_pipeline.rb

@@ -1,108 +0,0 @@
-# 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,
-            budget: build_token_budget,
-            instruction: build_instructions(inp),
-            tools: self.class.tools + _handoff_tools
-          )
-          apply_instructions(chat, context[:system]) if context[:system]
-          (context[:tool_classes] || []).each { |tc| chat.with_tool(prepare_tool_class(tc)) }
-          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