phronomy 0.11.0 → 0.12.0

data/lib/phronomy/workflow_runner.rb

@@ -79,29 +79,50 @@ module Phronomy
       caller_meta[:session_id] = config[:session_id] if config[:session_id]
 
       trace("workflow.invoke", input: input.inspect, **caller_meta) do |_span|
-        thread_id = config[:thread_id] || SecureRandom.uuid
-        recursion_limit = config.fetch(:recursion_limit, Phronomy.configuration.recursion_limit)
-
-        store = config.fetch(:state_store, @state_store) || Phronomy.configuration.state_store
-        snapshot = (store && config[:thread_id]) ? store.load(thread_id) : nil
-        initial_fields = if snapshot && snapshot[:fields]
-          snapshot[:fields].transform_keys(&:to_sym).merge(input.transform_keys(&:to_sym))
-        else
-          input
-        end
-
-        state = @state_class.new(**initial_fields)
-        state.set_graph_metadata(thread_id: thread_id)
-        result = if Phronomy.configuration.event_loop
-          run_via_event_loop(state, recursion_limit: recursion_limit)
-        else
-          run_workflow(state, recursion_limit: recursion_limit)
-        end
+        state, thread_id, recursion_limit, store = _build_initial_context(input, config)
+        result = run_via_event_loop(state, recursion_limit: recursion_limit)
         store&.save(thread_id, {fields: result.to_h, phase: result.phase.to_s}) if config[:thread_id]
         [result, nil]
       end
     end
 
+    # Registers the workflow with the EventLoop and returns a {Phronomy::Task}
+    # immediately without blocking the caller.  The task resolves with the final
+    # context when the workflow finishes.
+    #
+    # This is the EventLoop-driven equivalent of spawning a thread around
+    # {#invoke}.  No extra OS thread is created; the EventLoop's existing thread
+    # drives the execution.
+    #
+    # @param input [Hash] initial context field values
+    # @param config [Hash]
+    # @return [Phronomy::Task]
+    # @api private
+    def invoke_deferred(input, config: {})
+      state, thread_id, recursion_limit, store = _build_initial_context(input, config)
+      result_task = Phronomy::Task.deferred(name: "workflow-async:#{thread_id}")
+      Phronomy::EventLoop.instance.start
+      session = build_session_for(context: state, recursion_limit: recursion_limit)
+      if store && config[:thread_id]
+        # Wrap so that state is persisted when the task resolves.
+        persist_task = Phronomy::Task.deferred(name: "workflow-async-persist:#{thread_id}")
+        Phronomy::EventLoop.instance.register(session, completion: persist_task)
+        persist_task.on_complete do |result, error|
+          store.save(thread_id, {fields: result.to_h, phase: result.phase.to_s}) unless error
+          if error
+            result_task.backend.unblock(nil, error)
+            result_task.transition!(:failed, error: error)
+          else
+            result_task.backend.unblock(result, nil)
+            result_task.transition!(:completed, value: result)
+          end
+        end
+      else
+        Phronomy::EventLoop.instance.register(session, completion: result_task)
+      end
+      result_task
+    end
+
     # Generic resume. Equivalent to +send_event(state:, event: :resume, input:)+.
     # @param state [Object] halted context
     # @param input [Hash, nil] optional field updates to merge before resuming
@@ -142,13 +163,9 @@ module Phronomy
         event
       end
 
-      if Phronomy.configuration.event_loop
-        run_via_event_loop(state,
-          recursion_limit: Phronomy.configuration.recursion_limit,
-          resume_event: ev_to_fire, resume_phase: current_phase)
-      else
-        run_workflow(state, resume_event: ev_to_fire, resume_phase: current_phase)
-      end
+      run_via_event_loop(state,
+        recursion_limit: Phronomy.configuration.recursion_limit,
+        resume_event: ev_to_fire, resume_phase: current_phase)
     end
 
     # Streaming execution. Yields { state: Symbol, context: Object } after each state action completes.
@@ -167,9 +184,26 @@ module Phronomy
 
     private
 
+    # Builds the initial WorkflowContext from input and config.
+    # Returns [state, thread_id, recursion_limit, store].
+    def _build_initial_context(input, config)
+      thread_id = config[:thread_id] || SecureRandom.uuid
+      recursion_limit = config.fetch(:recursion_limit, Phronomy.configuration.recursion_limit)
+      store = config.fetch(:state_store, @state_store) || Phronomy.configuration.state_store
+      snapshot = (store && config[:thread_id]) ? store.load(thread_id) : nil
+      initial_fields = if snapshot && snapshot[:fields]
+        snapshot[:fields].transform_keys(&:to_sym).merge(input.transform_keys(&:to_sym))
+      else
+        input
+      end
+      state = @state_class.new(**initial_fields)
+      state.set_graph_metadata(thread_id: thread_id)
+      [state, thread_id, recursion_limit, store]
+    end
+
     # 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::Workflow::FSMSession.new(
+      Phronomy::FSMSession.new(
         id: context.thread_id,
         context: context,
         entry_point: @entry_point,
@@ -190,6 +224,9 @@ module Phronomy
     # Blocks the calling thread on a completion queue until the workflow
     # finishes, halts at a wait state, or raises an error.
     def run_via_event_loop(context, recursion_limit:, resume_event: nil, resume_phase: nil)
+      # Ensure EventLoop is running. In tests, reset_runtime! resets the
+      # singleton without restarting it; start is idempotent when already alive.
+      Phronomy::EventLoop.instance.start
       session = build_session_for(
         context: context, recursion_limit: recursion_limit,
         resume_event: resume_event, resume_phase: resume_phase
@@ -201,6 +238,19 @@ module Phronomy
     end
 
     def run_workflow(ctx, resume_event: nil, resume_phase: nil, recursion_limit: 25, &event_block)
+      # Mark the current thread as a synchronous execution context.
+      # This allows WorkflowContext field mutations via setters without raising
+      # WorkflowContextOwnershipError (which would otherwise fire since EventLoop
+      # is always active and run_workflow runs on the caller's thread).
+      Thread.current[:phronomy_sync_execution] = Thread.current[:phronomy_sync_execution].to_i + 1
+      _run_workflow_body(ctx, resume_event: resume_event, resume_phase: resume_phase,
+        recursion_limit: recursion_limit, &event_block)
+    ensure
+      depth = Thread.current[:phronomy_sync_execution].to_i - 1
+      Thread.current[:phronomy_sync_execution] = (depth > 0) ? depth : nil
+    end
+
+    def _run_workflow_body(ctx, resume_event: nil, resume_phase: nil, recursion_limit: 25, &event_block)
       if resume_event
         # -- Resume from a wait state -------------------------------------------
         # Fire the external event on a tracker positioned at the wait state.
@@ -231,7 +281,7 @@ module Phronomy
                   "Action in state #{current_state.inspect} timed out after #{timeout_secs}s"
               end
             end
-            task_result = result.await
+            task_result = result.wait_result
             ctx = task_result if task_result.is_a?(Phronomy::WorkflowContext)
           elsif result.is_a?(Phronomy::WorkflowContext)
             ctx = result

data/lib/phronomy.rb

@@ -11,11 +11,18 @@ loader.inflector.inflect("ruby_llm_embeddings" => "RubyLLMEmbeddings")
 # RAG: Zeitwerk would infer "Rag" — override to "RAG".
 loader.inflector.inflect("rag" => "RAG")
 # FSMSession: Zeitwerk would infer "FsmSession" — override to "FSMSession".
+# Phronomy::FSMSession is the top-level cooperative execution engine shared by
+# WorkflowRunner and Agent::InvocationSession.
 loader.inflector.inflect("fsm_session" => "FSMSession")
 # LLMAdapter: Zeitwerk would infer "LlmAdapter" — override to "LLMAdapter".
 loader.inflector.inflect("llm_adapter" => "LLMAdapter")
 # LLMAdapter::RubyLLM: "ruby_llm" maps to "RubyLLM" (not "RubyLlm").
 loader.inflector.inflect("ruby_llm" => "RubyLLM")
+# Collapse engine/ so that its contents autoload directly under Phronomy::
+# (no Engine:: prefix).  e.g. engine/event_loop.rb => Phronomy::EventLoop.
+# This allows the execution engine to be organised in its own subdirectory
+# without changing any class names or callers.
+loader.collapse("#{__dir__}/phronomy/engine")
 loader.setup
 
 require_relative "phronomy/version"
@@ -99,14 +106,6 @@ 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
@@ -187,8 +186,17 @@ module Phronomy
     #   config.around { |ex| Phronomy.reset_runtime! ; ex.run ; Phronomy.reset_runtime! }
     # @api public
     def reset_runtime!
-      Phronomy::EventLoop.reset!
+      # Do NOT stop the EventLoop here. Since Phase 2, all Agent#invoke calls
+      # go through FSMSession + EventLoop. Stopping and restarting the EventLoop
+      # on every after(:each) hook would add thread creation overhead per test.
+      # run_via_event_loop and _invoke_via_fsm restart it lazily if it was reset.
+      #
+      # Preserve event_loop_stop_grace_seconds from the current configuration
+      # so that test suites that set it to 0 (for fast teardown) keep that value
+      # across configuration resets.
+      prev_grace = @configuration&.event_loop_stop_grace_seconds
       @configuration = Configuration.new
+      @configuration.event_loop_stop_grace_seconds = prev_grace if prev_grace
     end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: phronomy
 version: !ruby/object:Gem::Version
-  version: 0.11.0
+  version: 0.12.0
 platform: ruby
 authors:
 - Raizo T.C.S
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-06-16 00:00:00.000000000 Z
+date: 2026-07-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ruby_llm
@@ -105,34 +105,54 @@ files:
 - lib/phronomy/agent.rb
 - 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/filterable.rb
 - lib/phronomy/agent/concerns/retryable.rb
-- lib/phronomy/agent/concerns/suspendable.rb
 - lib/phronomy/agent/context/capability/base.rb
 - lib/phronomy/agent/context/capability/scope_policy.rb
 - lib/phronomy/agent/context/instruction/prompt_template.rb
 - 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/invocation_context.rb
+- lib/phronomy/agent/invocation_session.rb
+- lib/phronomy/agent/phase_machine_builder.rb
 - lib/phronomy/agent/runner.rb
 - lib/phronomy/agent/shared_state.rb
-- lib/phronomy/agent/suspend_signal.rb
+- lib/phronomy/agent/suspended_session_registry.rb
+- lib/phronomy/agent/tool_call_intercepted.rb
 - lib/phronomy/agent/tool_executor.rb
-- lib/phronomy/concurrency/async_queue.rb
-- lib/phronomy/concurrency/blocking_adapter_pool.rb
-- lib/phronomy/concurrency/cancellation_scope.rb
-- lib/phronomy/concurrency/cancellation_token.rb
-- lib/phronomy/concurrency/concurrency_gate.rb
-- lib/phronomy/concurrency/deadline.rb
-- lib/phronomy/concurrency/gate_registry.rb
-- lib/phronomy/concurrency/pool_registry.rb
 - lib/phronomy/configuration.rb
-- lib/phronomy/context.rb
 - lib/phronomy/diagnostics.rb
+- lib/phronomy/engine/concurrency/async_queue.rb
+- lib/phronomy/engine/concurrency/blocking_adapter_pool.rb
+- lib/phronomy/engine/concurrency/cancellation_scope.rb
+- lib/phronomy/engine/concurrency/cancellation_token.rb
+- lib/phronomy/engine/concurrency/concurrency_gate.rb
+- lib/phronomy/engine/concurrency/deadline.rb
+- lib/phronomy/engine/concurrency/gate_registry.rb
+- lib/phronomy/engine/concurrency/pool_registry.rb
+- lib/phronomy/engine/event_loop.rb
+- lib/phronomy/engine/fsm_session.rb
+- lib/phronomy/engine/runtime.rb
+- lib/phronomy/engine/runtime/deterministic_scheduler.rb
+- lib/phronomy/engine/runtime/fake_scheduler.rb
+- lib/phronomy/engine/runtime/runtime_metrics.rb
+- lib/phronomy/engine/runtime/scheduler.rb
+- lib/phronomy/engine/runtime/scheduler_timer_adapter.rb
+- lib/phronomy/engine/runtime/task_registry.rb
+- lib/phronomy/engine/runtime/thread_scheduler.rb
+- lib/phronomy/engine/runtime/timer_queue.rb
+- lib/phronomy/engine/runtime/timer_service.rb
+- lib/phronomy/engine/task.rb
+- lib/phronomy/engine/task/backend.rb
+- lib/phronomy/engine/task/deferred_backend.rb
+- lib/phronomy/engine/task/fiber_backend.rb
+- lib/phronomy/engine/task/immediate_backend.rb
+- lib/phronomy/engine/task/mapped_backend.rb
+- lib/phronomy/engine/task/thread_backend.rb
+- lib/phronomy/engine/task_group.rb
 - lib/phronomy/eval.rb
 - lib/phronomy/eval/comparison.rb
 - lib/phronomy/eval/dataset.rb
@@ -146,7 +166,6 @@ files:
 - lib/phronomy/eval/scorer/includes_scorer.rb
 - lib/phronomy/eval/scorer/llm_judge.rb
 - lib/phronomy/event.rb
-- lib/phronomy/event_loop.rb
 - lib/phronomy/filter.rb
 - lib/phronomy/filter/base.rb
 - lib/phronomy/filter/prompt_injection_filter.rb
@@ -171,31 +190,13 @@ files:
 - lib/phronomy/output_parser/structured_parser.rb
 - lib/phronomy/ruby_llm_patches.rb
 - lib/phronomy/runnable.rb
-- lib/phronomy/runtime.rb
-- lib/phronomy/runtime/deterministic_scheduler.rb
-- lib/phronomy/runtime/fake_scheduler.rb
-- lib/phronomy/runtime/runtime_metrics.rb
-- lib/phronomy/runtime/scheduler.rb
-- lib/phronomy/runtime/scheduler_timer_adapter.rb
-- lib/phronomy/runtime/task_registry.rb
-- lib/phronomy/runtime/thread_scheduler.rb
-- lib/phronomy/runtime/timer_queue.rb
-- lib/phronomy/runtime/timer_service.rb
 - lib/phronomy/state_store/base.rb
 - lib/phronomy/state_store/in_memory.rb
-- lib/phronomy/task.rb
-- 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
 - lib/phronomy/testing/fake_clock.rb
 - lib/phronomy/testing/fake_scheduler.rb
 - lib/phronomy/testing/scheduler_helpers.rb
 - lib/phronomy/token_usage.rb
-- lib/phronomy/tool.rb
 - lib/phronomy/tools/agent.rb
 - lib/phronomy/tools/mcp.rb
 - lib/phronomy/tools/vector_search.rb
@@ -221,7 +222,6 @@ 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

data/lib/phronomy/agent/checkpoint.rb

@@ -1,208 +0,0 @@
-# frozen_string_literal: true
-
-require "securerandom"
-
-module Phronomy
-  module Agent
-    # Encapsulates the suspended state of an agent invocation.
-    #
-    # A Checkpoint is returned as the +:checkpoint+ key of the result hash when
-    # an approval-required tool is encountered and no synchronous
-    # on_approval_required handler has been registered.
-    #
-    # Pass the checkpoint to Agent::Base#resume to continue execution after
-    # obtaining an approval decision from the user or an external system.
-    #
-    # @example Suspend and resume
-    #   result = agent.invoke("Do task X")
-    #   if result[:suspended]
-    #     approved = prompt_user(result[:checkpoint].pending_tool_name)
-    #     result   = agent.resume(result[:checkpoint], approved: approved)
-    #   end
-    #   puts result[:output]
-    class Checkpoint
-      # @return [String] a globally unique identifier for this checkpoint;
-      #   used as an idempotency key when guarding against duplicate resumes
-      attr_reader :checkpoint_id
-
-      # @return [String, nil] the fully-qualified name of the agent class that
-      #   created this checkpoint (e.g. +"MyApp::ReviewAgent"+); used by the
-      #   class-level +resume+ method to validate the correct agent is used
-      attr_reader :agent_class
-
-      # @return [Time] the UTC timestamp when this checkpoint was created
-      attr_reader :requested_at
-
-      # @return [String, nil] the thread_id from the invocation config
-      attr_reader :thread_id
-
-      # @return [String, Hash] the original input passed to #invoke; stored so
-      #   that #resume can re-apply dynamic system instructions (e.g. Proc or
-      #   PromptTemplate-based instructions that depend on the input value).
-      attr_reader :original_input
-
-      # @return [Array<RubyLLM::Message>] conversation messages up to and including
-      #   the assistant message that requested the pending tool call
-      attr_reader :messages
-
-      # @return [String] the name of the tool awaiting approval
-      attr_reader :pending_tool_name
-
-      # @return [Hash] the arguments the LLM passed to the pending tool
-      attr_reader :pending_tool_args
-
-      # @return [String] the tool_call_id from the LLM response (required to
-      #   inject the tool result message on resume)
-      attr_reader :pending_tool_call_id
-
-      # @param checkpoint_id        [String] unique identifier; defaults to a new UUID
-      # @param agent_class           [String, nil] fully-qualified agent class name
-      # @param requested_at          [Time] when the checkpoint was created; defaults to +Time.now.utc+
-      # @param thread_id            [String, nil]
-      # @param original_input       [String, Hash] the input passed to the original #invoke call
-      # @param messages             [Array<RubyLLM::Message>]
-      # @param pending_tool_name    [String]
-      # @param pending_tool_args    [Hash]
-      # @param pending_tool_call_id [String]
-      # @api public
-      def initialize(thread_id:, original_input:, messages:, pending_tool_name:, pending_tool_args:, pending_tool_call_id:,
-        checkpoint_id: SecureRandom.uuid, agent_class: nil, requested_at: Time.now.utc)
-        @checkpoint_id = checkpoint_id
-        @agent_class = agent_class
-        @requested_at = requested_at
-        @thread_id = thread_id
-        @original_input = original_input
-        @messages = messages.dup.freeze
-        @pending_tool_name = pending_tool_name
-        @pending_tool_args = pending_tool_args
-        @pending_tool_call_id = pending_tool_call_id
-      end
-
-      # Converts this checkpoint to a plain Hash suitable for JSON / Marshal serialization.
-      #
-      # All values are plain Ruby objects (String, Symbol, Hash, Array, Numeric,
-      # nil). +RubyLLM::Message+ objects in +:messages+ are deep-converted so that
-      # any embedded +RubyLLM::ToolCall+ objects are also serialized as plain hashes.
-      #
-      # @example Round-trip via JSON
-      #   json = JSON.generate(checkpoint.to_h)
-      #   checkpoint2 = Phronomy::Agent::Checkpoint.from_h(JSON.parse(json))
-      #
-      # @return [Hash]
-      # @api public
-      def to_h
-        {
-          checkpoint_id: @checkpoint_id,
-          agent_class: @agent_class,
-          requested_at: @requested_at&.iso8601,
-          thread_id: @thread_id,
-          original_input: @original_input,
-          messages: @messages.map { |m| serialize_message(m) },
-          pending_tool_name: @pending_tool_name,
-          pending_tool_args: @pending_tool_args,
-          pending_tool_call_id: @pending_tool_call_id
-        }
-      end
-
-      # Reconstructs a +Checkpoint+ from a plain Hash (e.g. produced by {#to_h}
-      # and deserialized from JSON or Marshal).
-      #
-      # Hash keys may be either Symbols or Strings; both are accepted.
-      # +RubyLLM::ToolCall+ objects inside message +:tool_calls+ arrays are
-      # reconstructed from their hash representations.
-      #
-      # @param h [Hash] a hash previously produced by {#to_h}
-      # @return [Checkpoint]
-      # @api public
-      def self.from_h(h)
-        h = h.transform_keys { |k|
-          begin
-            k.to_sym
-          rescue
-            k
-          end
-        }
-        messages = Array(h[:messages]).map { |m| deserialize_message(m) }
-        requested_at_raw = h[:requested_at]
-        requested_at = requested_at_raw ? Time.parse(requested_at_raw.to_s).utc : nil
-        new(
-          checkpoint_id: h[:checkpoint_id]&.to_s || SecureRandom.uuid,
-          agent_class: h[:agent_class]&.to_s,
-          requested_at: requested_at || Time.now.utc,
-          thread_id: h[:thread_id],
-          original_input: h[:original_input],
-          messages: messages,
-          pending_tool_name: h[:pending_tool_name]&.to_s,
-          pending_tool_args: h[:pending_tool_args] ? h[:pending_tool_args].transform_keys { |k|
-            begin
-              k.to_sym
-            rescue
-              k
-            end
-          } : {},
-          pending_tool_call_id: h[:pending_tool_call_id]&.to_s
-        )
-      end
-
-      private
-
-      # Converts a +RubyLLM::Message+ to a plain Hash, ensuring that any
-      # embedded +RubyLLM::ToolCall+ objects in +:tool_calls+ are also converted.
-      #
-      # @param msg [RubyLLM::Message]
-      # @return [Hash]
-      # @api private
-      def serialize_message(msg)
-        h = msg.to_h
-        return h unless h[:tool_calls]
-
-        h.merge(tool_calls: h[:tool_calls].map { |tc|
-          tc.respond_to?(:to_h) ? tc.to_h : tc
-        })
-      end
-
-      # Reconstructs a +RubyLLM::Message+ from a plain Hash.
-      # +RubyLLM::ToolCall+ entries in +:tool_calls+ are re-instantiated.
-      #
-      # @param h [Hash]
-      # @return [RubyLLM::Message]
-      # @api private
-      def self.deserialize_message(h)
-        h = h.transform_keys { |k|
-          begin
-            k.to_sym
-          rescue
-            k
-          end
-        }
-        if h[:tool_calls]
-          h = h.merge(tool_calls: Array(h[:tool_calls]).map { |tc|
-            next tc if tc.is_a?(RubyLLM::ToolCall)
-
-            tc = tc.transform_keys { |k|
-              begin
-                k.to_sym
-              rescue
-                k
-              end
-            }
-            RubyLLM::ToolCall.new(
-              id: tc[:id].to_s,
-              name: tc[:name].to_s,
-              arguments: (tc[:arguments] || {}).transform_keys { |k|
-                begin
-                  k.to_sym
-                rescue
-                  k
-                end
-              },
-              thought_signature: tc[:thought_signature]
-            )
-          })
-        end
-        RubyLLM::Message.new(h)
-      end
-      private_class_method :deserialize_message
-    end
-  end
-end

data/lib/phronomy/agent/checkpoint_store.rb

@@ -1,97 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Agent
-    # Default in-memory idempotency store for {Checkpoint} resume operations.
-    #
-    # Tracks consumed checkpoint IDs so that calling {Agent::Base#resume} twice
-    # with the same checkpoint raises {Phronomy::CheckpointAlreadyResumedError}
-    # instead of silently executing the approved tool a second time.
-    #
-    # This implementation is *not thread-safe*. It assumes a single agent instance
-    # is accessed from only one thread at a time, which is the expected usage pattern.
-    # Agent instances themselves are not thread-safe (state like +@messages+, +@config+
-    # is not protected), so concurrent calls to the same agent instance are unsupported.
-    #
-    # Each agent instance gets its own store by default, so no sharing occurs unless
-    # the caller explicitly assigns the same store object to multiple agents.
-    #
-    # For distributed environments (multiple processes or background jobs), swap this
-    # for a custom implementation backed by Redis, ActiveRecord, or another shared store.
-    # *Your custom store implementation is responsible for ensuring thread-safety* if
-    # your application shares the same store instance across multiple threads.
-    #
-    # @example Plugging in a custom store
-    #   agent = MyAgent.new
-    #   agent.checkpoint_store = MyRedis::CheckpointStore.new
-    #
-    # @example Duck-type contract required by any replacement
-    #   # consumed?(checkpoint_id) => Boolean
-    #   # consume!(checkpoint_id)  => void; raises CheckpointAlreadyResumedError if duplicate
-    #   # cleanup!(checkpoint_id)  => void (optional); removes tracking for the checkpoint
-    #   # clear!                   => void (optional); removes all tracked checkpoints
-    #
-    # @api public
-    class CheckpointStore
-      def initialize
-        @consumed = Set.new
-      end
-
-      # Returns +true+ if the given checkpoint ID has already been consumed.
-      #
-      # @param checkpoint_id [String]
-      # @return [Boolean]
-      # @api public
-      def consumed?(checkpoint_id)
-        @consumed.include?(checkpoint_id)
-      end
-
-      # Marks +checkpoint_id+ as consumed, or raises if it was already consumed.
-      #
-      # @param checkpoint_id [String]
-      # @raise [Phronomy::CheckpointAlreadyResumedError]
-      # @return [void]
-      # @api public
-      def consume!(checkpoint_id)
-        if @consumed.include?(checkpoint_id)
-          raise Phronomy::CheckpointAlreadyResumedError,
-            "checkpoint #{checkpoint_id} has already been resumed"
-        end
-        @consumed.add(checkpoint_id)
-        nil
-      end
-
-      # Removes tracking for a specific checkpoint ID.
-      #
-      # Use this to explicitly discard a checkpoint when the application
-      # determines it is no longer needed (e.g., user abandons an approval
-      # workflow).
-      #
-      # This method is optional in the duck-type contract. Custom store
-      # implementations may choose not to implement it.
-      #
-      # @param checkpoint_id [String]
-      # @return [void]
-      # @api public
-      def cleanup!(checkpoint_id)
-        @consumed.delete(checkpoint_id)
-        nil
-      end
-
-      # Removes all tracked checkpoint IDs.
-      #
-      # Use this for test cleanup, periodic maintenance, or application
-      # shutdown.
-      #
-      # This method is optional in the duck-type contract. Custom store
-      # implementations may choose not to implement it.
-      #
-      # @return [void]
-      # @api public
-      def clear!
-        @consumed.clear
-        nil
-      end
-    end
-  end
-end