Class: Phronomy::Agent::CheckpointStore

Inherits:
Object
  • Object
show all
Defined in:
lib/phronomy/agent/checkpoint_store.rb

Overview

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

Examples:

Plugging in a custom store

agent = MyAgent.new
agent.checkpoint_store = MyRedis::CheckpointStore.new

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

Instance Method Summary collapse

Constructor Details

#initialize ⇒ CheckpointStore

Returns a new instance of CheckpointStore.



36
37
38
 
# File 'lib/phronomy/agent/checkpoint_store.rb', line 36

def initialize
  @consumed = Set.new
end

Instance Method Details

#cleanup!(checkpoint_id) ⇒ void

This method returns an undefined value.

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.

Parameters:

  • checkpoint_id (String) 


76
77
78
79
 
# File 'lib/phronomy/agent/checkpoint_store.rb', line 76

def cleanup!(checkpoint_id)
  @consumed.delete(checkpoint_id)
  nil
end

#clear! ⇒ void

This method returns an undefined value.

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.



91
92
93
94
 
# File 'lib/phronomy/agent/checkpoint_store.rb', line 91

def clear!
  @consumed.clear
  nil
end

#consume!(checkpoint_id) ⇒ void

This method returns an undefined value.

Marks +checkpoint_id+ as consumed, or raises if it was already consumed.

Parameters:

  • checkpoint_id (String)

Raises:



55
56
57
58
59
60
61
62
 
# File 'lib/phronomy/agent/checkpoint_store.rb', line 55

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

#consumed?(checkpoint_id) ⇒ Boolean

Returns +true+ if the given checkpoint ID has already been consumed.

Parameters:

  • checkpoint_id (String)

Returns:

  • (Boolean) 


45
46
47
 
# File 'lib/phronomy/agent/checkpoint_store.rb', line 45

def consumed?(checkpoint_id)
  @consumed.include?(checkpoint_id)
end