phronomy 0.1.4 → 0.2.1

data/lib/phronomy/memory/retrieval/semantic.rb

@@ -28,7 +28,7 @@ module Phronomy
           @index = {}   # id => message  (insertion-ordered via Ruby Hash)
           @counter = 0
           @max_index_size = max_index_size
-          @mutex = Mutex.new
+          @actor = Phronomy::Actor.new
           @indexed_object_ids = {}  # thread_id => { object_id => true }
         end
 
@@ -43,14 +43,14 @@ module Phronomy
         def index(thread_id:, messages:)
           messages.each do |msg|
             # Fast path: skip already-indexed messages without calling embed.
-            already_indexed = @mutex.synchronize do
+            already_indexed = @actor.call do
               (@indexed_object_ids[thread_id] ||= {})[msg.object_id]
             end
             next if already_indexed
 
             embedding = @embeddings.embed(msg.content.to_s)
-            @mutex.synchronize do
-              # Re-check inside lock to handle concurrent callers for the same thread.
+            @actor.call do
+              # Re-check inside Actor to handle concurrent callers for the same thread.
               indexed = (@indexed_object_ids[thread_id] ||= {})
               next if indexed[msg.object_id]
 
@@ -68,7 +68,7 @@ module Phronomy
         #
         # @param thread_id [String]
         def clear_index(thread_id:)
-          @mutex.synchronize do
+          @actor.call do
             ids = @index.keys.select { |id| id.start_with?("#{thread_id}:") }
             ids.each do |id|
               @index.delete(id)
@@ -87,7 +87,7 @@ module Phronomy
         def select(messages, query: nil, thread_id: nil)
           if query && !query.strip.empty?
             query_embedding = @embeddings.embed(query)
-            results = @mutex.synchronize { @store.search(query_embedding: query_embedding, k: @k * 3) }
+            results = @actor.call { @store.search(query_embedding: query_embedding, k: @k * 3) }
             results
               .select { |r| thread_id.nil? || r[:metadata][:thread_id] == thread_id }
               .first(@k)
@@ -100,7 +100,7 @@ module Phronomy
         private
 
         # Evicts the oldest index entry to enforce max_index_size.
-        # Must be called inside @mutex.synchronize.
+        # Must be called inside the Actor.
         def evict_oldest!
           oldest_id = @index.keys.first
           return unless oldest_id

data/lib/phronomy/memory/storage/active_record.rb

@@ -170,6 +170,26 @@ module Phronomy
           @model_class.where(thread_id: thread_id).where("created_at < ?", older_than).delete_all
         end
 
+        # Returns the next seq number to use for new raw messages for +thread_id+.
+        # Derived from MAX(seq) in the database; since purge_older_than does not
+        # touch raw records, this value is always correct.
+        #
+        # @param thread_id [String]
+        # @return [Integer]
+        def next_seq(thread_id:)
+          return 0 unless @raw_model_class
+
+          ((@raw_model_class.where(thread_id: thread_id).maximum(:seq) || -1) + 1)
+        end
+
+        # Delegates to the block directly; serialisation of concurrent saves
+        # for the same thread_id is the caller's responsibility (e.g. DB-level
+        # transaction isolation or application-layer queuing).
+        # @param thread_id [String]
+        def with_thread_lock(thread_id:)
+          yield
+        end
+
         private
 
         def ensure_raw_model!

data/lib/phronomy/memory/storage/base.rb

@@ -127,6 +127,28 @@ module Phronomy
         def purge_older_than(thread_id:, older_than:)
           # no-op by default
         end
+
+        # Returns the next seq number to assign when appending new raw messages
+        # for +thread_id+. Must be monotonically increasing and must survive
+        # purge_older_than (i.e. the counter must not reset when old raw records
+        # are deleted by a TTL purge).
+        #
+        # @param thread_id [String]
+        # @return [Integer]
+        def next_seq(thread_id:)
+          raise NotImplementedError, "#{self.class}#next_seq is not implemented"
+        end
+
+        # Executes the block while holding a per-thread-id lock for +thread_id+.
+        # Used by ConversationManager to prevent concurrent compaction for the
+        # same thread. The default implementation yields without locking; backends
+        # that require serialisation should override this method.
+        #
+        # @param thread_id [String]
+        # @yield
+        def with_thread_lock(thread_id:)
+          yield
+        end
       end
     end
   end

data/lib/phronomy/memory/storage/in_memory.rb

@@ -3,18 +3,19 @@
 module Phronomy
   module Memory
     module Storage
-      # In-process Hash-backed storage for conversation messages.
+      # In-process storage for conversation messages backed by per-thread-id
+      # {Phronomy::Actor} instances from {Phronomy::ThreadActorRegistry}.
       # Messages are lost when the process exits.
       #
       # @example
       #   storage = Phronomy::Memory::Storage::InMemory.new
       #   manager = Phronomy::Memory::ConversationManager.new(storage: storage, ...)
       class InMemory < Base
+        # Thread-local key for per-thread-id storage data (namespaced by store
+        # instance object_id to support multiple independent InMemory stores).
+        THREAD_DATA_KEY = :phronomy_storage_in_memory_data
+
         def initialize
-          @mutex = Mutex.new
-          @store = {}
-          @raw_store = {}       # thread_id => [{seq:, message:}, ...]
-          @compaction_store = {} # thread_id => [{start_seq:, end_seq:, summary_text:}, ...]
         end
 
         # -----------------------------------------------------------------------
@@ -24,21 +25,20 @@ module Phronomy
         # @param thread_id [String]
         # @return [Array]
         def load(thread_id:)
-          @mutex.synchronize { (@store[thread_id] || []).dup }
+          Phronomy::ThreadActorRegistry.for(thread_id).call { (thread_data.store || []).dup }
         end
 
         # @param thread_id [String]
         # @param messages  [Array]
         def save(thread_id:, messages:)
-          @mutex.synchronize { @store[thread_id] = messages.dup }
+          Phronomy::ThreadActorRegistry.for(thread_id).call { thread_data.store = messages.dup }
         end
 
         # @param thread_id [String]
         def clear(thread_id:)
-          @mutex.synchronize do
-            @store.delete(thread_id)
-            @raw_store.delete(thread_id)
-            @compaction_store.delete(thread_id)
+          store_id = object_id
+          Phronomy::ThreadActorRegistry.for(thread_id).call do
+            (Thread.current[THREAD_DATA_KEY] ||= {}).delete(store_id)
           end
         end
 
@@ -49,25 +49,45 @@ module Phronomy
         # @param thread_id    [String]
         # @param messages     [Array]
         # @param starting_seq [Integer]
-        def append_raw(thread_id:, messages:, starting_seq:)
-          now = Time.now
-          @mutex.synchronize do
-            @raw_store[thread_id] ||= []
+        # @param recorded_at  [Time, nil] timestamp for test overrides; defaults to +Time.now+
+        def append_raw(thread_id:, messages:, starting_seq:, recorded_at: nil)
+          now = recorded_at || Time.now
+          Phronomy::ThreadActorRegistry.for(thread_id).call do
+            data = thread_data
             messages.each_with_index do |msg, i|
-              @raw_store[thread_id] << {seq: starting_seq + i, message: msg, recorded_at: now}
+              seq = starting_seq + i
+              data.raw_messages << {seq: seq, message: msg, recorded_at: now}
+              data.hwm = [data.hwm, seq].max
             end
           end
         end
 
+        # @param thread_id [String]
+        # @return [Integer]
+        def next_seq(thread_id:)
+          Phronomy::ThreadActorRegistry.for(thread_id).call { thread_data.hwm + 1 }
+        end
+
+        # Routes +block+ through the per-thread-id {Phronomy::Actor}, serialising
+        # all operations for the same thread.  Reentrant calls (the block itself
+        # calling storage methods that also route through the Actor) are safe
+        # because {Phronomy::Actor#call} detects the same-thread case and executes
+        # inline.
+        #
+        # @param thread_id [String]
+        def with_thread_lock(thread_id:, &block)
+          Phronomy::ThreadActorRegistry.for(thread_id).call(&block)
+        end
+
         # @param thread_id [String]
         # @return [Array<Hash>]
         def load_raw(thread_id:)
-          @mutex.synchronize { (@raw_store[thread_id] || []).dup }
+          Phronomy::ThreadActorRegistry.for(thread_id).call { thread_data.raw_messages.dup }
         end
 
         # @param thread_id [String]
         def clear_raw(thread_id:)
-          @mutex.synchronize { @raw_store.delete(thread_id) }
+          Phronomy::ThreadActorRegistry.for(thread_id).call { thread_data.raw_messages.clear }
         end
 
         # -----------------------------------------------------------------------
@@ -79,21 +99,20 @@ module Phronomy
         # @param end_seq      [Integer]
         # @param summary_text [String]
         def save_compaction(thread_id:, start_seq:, end_seq:, summary_text:)
-          @mutex.synchronize do
-            @compaction_store[thread_id] ||= []
-            @compaction_store[thread_id] << {start_seq: start_seq, end_seq: end_seq, summary_text: summary_text}
+          Phronomy::ThreadActorRegistry.for(thread_id).call do
+            thread_data.compactions << {start_seq: start_seq, end_seq: end_seq, summary_text: summary_text}
           end
         end
 
         # @param thread_id [String]
         # @return [Array<Hash>]
         def load_compactions(thread_id:)
-          @mutex.synchronize { (@compaction_store[thread_id] || []).dup }
+          Phronomy::ThreadActorRegistry.for(thread_id).call { thread_data.compactions.dup }
         end
 
         # @param thread_id [String]
         def clear_compactions(thread_id:)
-          @mutex.synchronize { @compaction_store.delete(thread_id) }
+          Phronomy::ThreadActorRegistry.for(thread_id).call { thread_data.compactions.clear }
         end
 
         # Remove raw messages recorded before +older_than+ for this thread.
@@ -101,10 +120,30 @@ module Phronomy
         # @param thread_id  [String]
         # @param older_than [Time]
         def purge_older_than(thread_id:, older_than:)
-          @mutex.synchronize do
-            next unless @raw_store[thread_id]
+          Phronomy::ThreadActorRegistry.for(thread_id).call do
+            thread_data.raw_messages.reject! { |entry| entry[:recorded_at] && entry[:recorded_at] < older_than }
+          end
+        end
+
+        private
+
+        # Returns (or lazily initialises) the {ThreadData} for the current Actor
+        # thread and this storage instance.  Must only be called from within a
+        # {Phronomy::ThreadActorRegistry.for} block so that +Thread.current+ is
+        # the correct Actor thread.
+        def thread_data
+          (Thread.current[THREAD_DATA_KEY] ||= {})[object_id] ||= ThreadData.new
+        end
+
+        # Value object holding all per-thread-id storage state.
+        class ThreadData
+          attr_accessor :store, :raw_messages, :compactions, :hwm
 
-            @raw_store[thread_id].reject! { |entry| entry[:recorded_at] && entry[:recorded_at] < older_than }
+          def initialize
+            @store = nil
+            @raw_messages = []
+            @compactions = []
+            @hwm = -1
           end
         end
       end

data/lib/phronomy/state_store/active_record.rb

@@ -38,7 +38,7 @@ module Phronomy
       end
 
       # Serializes and upserts the state for the given thread_id.
-      # @param state [Object] includes Phronomy::Graph::State
+      # @param state [Object] includes Phronomy::WorkflowContext
       # @return [self]
       def save(state)
         json = serialize_state(state)

data/lib/phronomy/state_store/base.rb

@@ -7,11 +7,11 @@ module Phronomy
     # Abstract base class for state persistence backends.
     # Subclasses must implement save, load, and clear.
     #
-    # The state object passed to save must include Phronomy::Graph::State
-    # and have a non-nil thread_id (set automatically by CompiledGraph#invoke).
+    # The state object passed to save must include Phronomy::WorkflowContext
+    # and have a non-nil thread_id (set automatically by WorkflowRunner#invoke).
     class Base
       # Persists the state. The thread_id is read from state.thread_id.
-      # @param state [Object] object including Phronomy::Graph::State
+      # @param state [Object] object including Phronomy::WorkflowContext
       # @return [self]
       def save(state)
         raise NotImplementedError, "#{self.class}#save is not implemented"
@@ -40,8 +40,7 @@ module Phronomy
           state_class: state.class.name,
           state_data: json_safe(state.to_h),
           thread_id: state.thread_id,
-          current_nodes: state.current_nodes&.map(&:to_s),
-          halted_before: state.halted_before
+          phase: state.phase&.to_s
         )
       end
 
@@ -54,37 +53,36 @@ module Phronomy
         state = state_class.new(**state_data)
         state.set_graph_metadata(
           thread_id: data[:thread_id],
-          current_nodes: data[:current_nodes]&.map(&:to_sym),
-          halted_before: data[:halted_before]
+          phase: data[:phase]&.to_sym
         )
         state
       end
 
-      # Resolves and validates a state class name.
-      # When a registry has been configured via +Phronomy::Graph.register_state_class+,
+      # Resolves and validates a context class name.
+      # When a registry has been configured via +Phronomy.register_workflow_context+,
       # only registered classes are accepted — this prevents unintended autoloading
       # of arbitrary files from an untrusted class name stored in Redis/DB.
       # When no registry is configured, falls back to Object.const_get with a check
-      # that the resolved class includes Phronomy::Graph::State.
+      # that the resolved class includes Phronomy::WorkflowContext.
       def safe_state_class(class_name)
-        registry = Phronomy::Graph.state_class_registry
+        registry = Phronomy.workflow_context_registry
         if registry
           klass = registry[class_name.to_s]
           unless klass
             raise ArgumentError,
-              "Unregistered state class: #{class_name.inspect}. " \
-              "Call Phronomy::Graph.register_state_class(#{class_name}) at startup."
+              "Unregistered context class: #{class_name.inspect}. " \
+              "Call Phronomy.register_workflow_context(#{class_name}) at startup."
           end
           return klass
         end
 
         klass = Object.const_get(class_name.to_s)
-        unless klass.is_a?(Class) && klass.include?(Phronomy::Graph::State)
-          raise ArgumentError, "Invalid state class: #{class_name.inspect}"
+        unless klass.is_a?(Class) && klass.include?(Phronomy::WorkflowContext)
+          raise ArgumentError, "Invalid context class: #{class_name.inspect}"
         end
         klass
       rescue NameError
-        raise ArgumentError, "Unknown state class: #{class_name.inspect}"
+        raise ArgumentError, "Unknown context class: #{class_name.inspect}"
       end
 
       # Recursively converts objects to JSON-safe primitives.

data/lib/phronomy/state_store/file.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+
+module Phronomy
+  module StateStore
+    # File-system-backed state store.
+    # Persists graph state as a JSON file under a configurable directory.
+    # No additional server or database migration is required — it works with
+    # the local file system out of the box.
+    #
+    # Each thread_id is stored as a separate file named "<thread_id>.json".
+    # The thread_id is sanitised before use as a filename to prevent path
+    # traversal: only alphanumeric characters, hyphens, underscores, and dots
+    # are allowed; all other characters are replaced with underscores.
+    #
+    # @note This store is suitable for single-process use (development, CLI
+    #   tools, tests).  It is not safe for concurrent access across multiple
+    #   processes without external locking.
+    #
+    # @example
+    #   store = Phronomy::StateStore::File.new(dir: "tmp/workflow_states")
+    #   Phronomy::Workflow.define(MyContext, state_store: store) do
+    #     # ...
+    #   end
+    class File < Base
+      # @param dir [String] directory where state files are stored.
+      #   Created automatically if it does not exist.
+      def initialize(dir: ::File.join(::Dir.tmpdir, "phronomy_states"))
+        @dir = ::File.expand_path(dir)
+        ::FileUtils.mkdir_p(@dir)
+      end
+
+      # @param state [Object] includes Phronomy::WorkflowContext; must have a non-nil thread_id
+      # @return [self]
+      def save(state)
+        ::File.write(path(state.thread_id), serialize_state(state))
+        self
+      end
+
+      # @param thread_id [String]
+      # @return [Object, nil] state instance or nil if not found
+      def load(thread_id)
+        file = path(thread_id)
+        return nil unless ::File.exist?(file)
+
+        deserialize_state(::File.read(file))
+      end
+
+      # Removes the saved state file for the given thread_id.
+      # @param thread_id [String]
+      # @return [self]
+      def clear(thread_id)
+        file = path(thread_id)
+        ::File.delete(file) if ::File.exist?(file)
+        self
+      end
+
+      # Removes all state files managed by this store instance.
+      # @return [self]
+      def clear_all
+        ::Dir.glob(::File.join(@dir, "*.json")).each { |f| ::File.delete(f) }
+        self
+      end
+
+      # @return [String] the directory used by this store
+      def directory
+        @dir
+      end
+
+      private
+
+      # Converts a thread_id into a safe filename component.
+      # Characters outside [A-Za-z0-9._-] are replaced with underscores.
+      def sanitize(thread_id)
+        thread_id.to_s.gsub(/[^A-Za-z0-9._-]/, "_")
+      end
+
+      def path(thread_id)
+        ::File.join(@dir, "#{sanitize(thread_id)}.json")
+      end
+    end
+  end
+end

data/lib/phronomy/state_store/in_memory.rb

@@ -2,37 +2,50 @@
 
 module Phronomy
   module StateStore
-    # In-memory state store. Stores state objects keyed by thread_id.
-    # State objects are stored directly (no serialization), so this
-    # backend is suitable for single-process use only.
+    # In-memory state store backed by per-thread-id {Phronomy::Actor} instances
+    # from {Phronomy::ThreadActorRegistry}. Suitable for single-process use only.
     class InMemory < Base
+      # Thread-local key for per-thread-id state data (namespaced by store
+      # instance object_id to support multiple independent InMemory stores).
+      THREAD_DATA_KEY = :phronomy_state_store_in_memory_data
+
       def initialize
-        @store = {}
-        @mutex = Mutex.new
       end
 
-      # @param state [Object] includes Phronomy::Graph::State; must have a non-nil thread_id
+      # @param state [Object] includes Phronomy::WorkflowContext; must have a non-nil thread_id
       # @return [self]
       def save(state)
-        @mutex.synchronize { @store[state.thread_id] = state }
+        store_id = object_id
+        Phronomy::ThreadActorRegistry.for(state.thread_id).call do
+          (Thread.current[THREAD_DATA_KEY] ||= {})[store_id] = state
+        end
         self
       end
 
       # @param thread_id [String]
       # @return [Object, nil] state object or nil
       def load(thread_id)
-        @mutex.synchronize { @store[thread_id] }
+        store_id = object_id
+        Phronomy::ThreadActorRegistry.for(thread_id).call do
+          (Thread.current[THREAD_DATA_KEY] ||= {})[store_id]
+        end
       end
 
       # @param thread_id [String]
       # @return [self]
       def clear(thread_id)
-        @mutex.synchronize { @store.delete(thread_id) }
+        store_id = object_id
+        Phronomy::ThreadActorRegistry.for(thread_id).call do
+          (Thread.current[THREAD_DATA_KEY] ||= {}).delete(store_id)
+        end
         self
       end
 
       def clear_all
-        @mutex.synchronize { @store.clear }
+        store_id = object_id
+        Phronomy::ThreadActorRegistry.each_actor do |actor|
+          actor.call { (Thread.current[THREAD_DATA_KEY] ||= {}).delete(store_id) }
+        end
         self
       end
     end

data/lib/phronomy/state_store/redis.rb

@@ -33,7 +33,7 @@ module Phronomy
         @ttl = ttl
       end
 
-      # @param state [Object] includes Phronomy::Graph::State
+      # @param state [Object] includes Phronomy::WorkflowContext
       # @return [self]
       def save(state)
         serialized = serialize_state(state)

data/lib/phronomy/thread_actor_registry.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Phronomy
+  # Global per-thread-id {Actor} registry.
+  #
+  # Maps the +:thread_id+ key from the +config:+ argument passed to
+  # {Phronomy::Agent::Base#invoke} to a {Phronomy::Actor} instance.
+  # Each thread_id gets exactly one Actor so that all operations for the same
+  # conversation are serialised automatically.
+  #
+  # @example
+  #   Phronomy::ThreadActorRegistry.for("user-42").call do
+  #     # runs sequentially on the Actor's thread
+  #   end
+  module ThreadActorRegistry
+    @actors = {}
+    @registry_actor = Actor.new
+
+    class << self
+      # Returns (or lazily creates) the {Actor} for +thread_id+.
+      #
+      # @param thread_id [String]
+      # @return [Phronomy::Actor]
+      def for(thread_id)
+        @registry_actor.call { @actors[thread_id] ||= Actor.new }
+      end
+
+      # Gracefully stops the Actor for +thread_id+ and removes it from the
+      # registry.  The next call to {.for} with the same id creates a fresh Actor.
+      #
+      # @param thread_id [String]
+      def stop(thread_id)
+        @registry_actor.call { @actors.delete(thread_id) }&.stop
+      end
+
+      # Stops and removes every registered Actor.
+      # Intended for test teardown and process shutdown.
+      def clear_all
+        actors = @registry_actor.call { @actors.values.tap { @actors.clear } }
+        actors.each(&:stop)
+      end
+
+      # Yields each currently registered Actor.
+      # A snapshot is taken so the registry cannot change while callers iterate.
+      #
+      # @yield [Phronomy::Actor]
+      def each_actor(&block)
+        @registry_actor.call { @actors.values.dup }.each(&block)
+      end
+    end
+  end
+end

data/lib/phronomy/tool/base.rb

@@ -58,7 +58,7 @@ module Phronomy
         end
 
         # Sets the access scope for this tool (metadata; enforcement is the responsibility of
-        # the Graph/Guardrail layer).
+        # the Workflow/Guardrail layer).
         # @param value [Symbol] e.g. :read_only, :write, :admin
         def scope(value = nil)
           return @scope if value.nil?

data/lib/phronomy/tool/mcp_tool.rb

@@ -87,7 +87,7 @@ module Phronomy
           # Split the command string into an argv array so that Open3 executes
           # it directly without going through the shell, preventing injection.
           @command = Shellwords.split(command)
-          @mutex = Mutex.new
+          @actor = Phronomy::Actor.new
           @stdin = nil
           @stdout = nil
           @stderr = nil
@@ -97,20 +97,21 @@ module Phronomy
 
         # Shut down the child process and close its IO streams.
         def close
-          @mutex.synchronize do
+          stderr_thread, wait_thr = @actor.call do
             @stdin&.close
             @stdout&.close
             @stderr&.close
             @stdin = nil
             @stdout = nil
             @stderr = nil
+            t = [@stderr_thread, @wait_thr]
+            @stderr_thread = nil
+            @wait_thr = nil
+            t
           end
-          # Join the stderr drain thread and the child process outside the mutex
-          # to avoid holding the lock during potentially slow joins.
-          @stderr_thread&.join(1)
-          @wait_thr&.join(5)
-          @stderr_thread = nil
-          @wait_thr = nil
+          # Join outside the Actor to avoid blocking the Actor thread on slow joins.
+          stderr_thread&.join(1)
+          wait_thr&.join(5)
         end
 
         # Retrieve the tool definition from the server using the MCP `tools/list` method.
@@ -167,7 +168,7 @@ module Phronomy
         end
 
         def rpc_call(method, params)
-          @mutex.synchronize do
+          @actor.call do
             ensure_started!
             payload = JSON.generate(jsonrpc: "2.0", id: SecureRandom.uuid, method: method, params: params)
             @stdin.puts(payload)

data/lib/phronomy/tracing/langfuse_tracer.rb

@@ -36,7 +36,7 @@ module Phronomy
         @secret_key = secret_key
         @host = host.chomp("/")
         @http = nil
-        @http_mutex = Mutex.new
+        @actor = Phronomy::Actor.new
       end
 
       # Returns a plain Hash that records the span start state.
@@ -90,13 +90,13 @@ module Phronomy
         req["Authorization"] = "Basic #{Base64.strict_encode64("#{@public_key}:#{@secret_key}")}"
         req.body = JSON.generate({batch: events})
 
-        @http_mutex.synchronize do
+        @actor.call do
           @http ||= build_http(uri)
           @http.request(req)
         end
       rescue IOError, Errno::ECONNRESET, Errno::EPIPE => e
         # Connection was reset; drop the cached connection and warn.
-        @http_mutex.synchronize { @http = nil }
+        @actor.call { @http = nil }
         warn "[Phronomy::LangfuseTracer] Ingestion failed: #{e.class}: #{e.message}"
         nil
       rescue => e