phronomy 0.8.0 → 0.9.1

data/lib/phronomy/agent/checkpoint.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "securerandom"
+
 module Phronomy
   module Agent
     # Encapsulates the suspended state of an agent invocation.
@@ -19,6 +21,18 @@ module Phronomy
     #   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
 
@@ -41,6 +55,9 @@ module Phronomy
       #   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>]
@@ -48,7 +65,11 @@ module Phronomy
       # @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:)
+      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
@@ -71,6 +92,9 @@ module Phronomy
       # @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) },
@@ -99,7 +123,12 @@ module Phronomy
           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,

data/lib/phronomy/agent/checkpoint_store.rb

@@ -0,0 +1,97 @@
+# 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

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

@@ -49,7 +49,7 @@ module Phronomy
 
         private
 
-        # Retry loop for #invoke. Separated so that ReactAgent can override #invoke_once.
+        # Retry loop for #invoke.
         def _invoke_impl(input, messages: [], thread_id: nil, config: {})
           # Fail fast when the token is already cancelled before any LLM call.
           if (token = config[:cancellation_token]) && token.cancelled?

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,18 +78,23 @@ 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
 
-          # Re-apply system instructions so the LLM has the same persona/context
-          # as the original invocation. build_cached_system_text is memoised, so
-          # a Proc- or PromptTemplate-based instructions block is re-evaluated
-          # against the original input rather than using a stale cached value.
-          system_text = build_cached_system_text(checkpoint.original_input)
-          apply_instructions(chat, system_text) if system_text
+          # Re-apply system instructions and register tools so the LLM has the
+          # same persona/context as the original invocation. build_context
+          # includes all tool classes (static + handoff) via add_capability.
+          context = build_context(checkpoint.original_input, messages: [])
+          apply_instructions(chat, context[:system]) if context[:system]
+          (context[:tool_classes] || []).each { |tc| chat.with_tool(prepare_tool_class(tc)) }
 
           # Restore the full conversation (history + user + assistant with tool call).
           checkpoint.messages.each { |msg| chat.messages << msg }
@@ -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