phronomy 0.1.3 → 0.2.0

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/in_memory.rb

@@ -2,36 +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 = {}
       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)
-        @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)
-        @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)
-        @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
-        @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?
@@ -157,7 +157,14 @@ module Phronomy
           key = properties.key?(param_name.to_s) ? param_name.to_s : param_name.to_sym
           next unless properties[key]
 
-          properties[key]["enum"] = values.map(&:to_s)
+          param_type = properties[key]["type"]
+          properties[key]["enum"] = values.map do |v|
+            case param_type
+            when "integer" then v.is_a?(Integer) ? v : Integer(v.to_s)
+            when "number" then v.is_a?(Numeric) ? v : Float(v.to_s)
+            else v.to_s
+            end
+          end
         end
 
         schema

data/lib/phronomy/tool/mcp_tool.rb

@@ -87,19 +87,31 @@ 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
+          @wait_thr = nil
+          @stderr_thread = nil
         end
 
         # 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 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.
@@ -144,11 +156,19 @@ module Phronomy
         def ensure_started!
           return if @stdin && !@stdin.closed?
 
-          @stdin, @stdout, _stderr, _wait_thr = Open3.popen3(*@command)
+          @stdin, @stdout, @stderr, @wait_thr = Open3.popen3(*@command)
+          # Drain stderr asynchronously to prevent the pipe buffer from filling
+          # and deadlocking the child process. Errors inside the drain thread are
+          # silently ignored since stderr content is diagnostics-only.
+          @stderr_thread = Thread.new do
+            @stderr.read
+          rescue
+            nil
+          end
         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)
@@ -212,6 +232,10 @@ module Phronomy
         # @return [Object] the tool result
         def call_tool(tool_name, args)
           response = rpc_call("tools/call", {name: tool_name, arguments: args})
+          if response["error"]
+            err_msg = response.dig("error", "message") || response["error"].to_s
+            raise Phronomy::ToolError, "MCP HTTP server returned error: #{err_msg}"
+          end
           content = response.dig("result", "content")
 
           if content.is_a?(Array)

data/lib/phronomy/tracing/base.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require "ostruct"
-
 module Phronomy
   module Tracing
     # Abstract tracer.

data/lib/phronomy/tracing/langfuse_tracer.rb

@@ -35,6 +35,8 @@ module Phronomy
         @public_key = public_key
         @secret_key = secret_key
         @host = host.chomp("/")
+        @http = nil
+        @actor = Phronomy::Actor.new
       end
 
       # Returns a plain Hash that records the span start state.
@@ -78,21 +80,37 @@ module Phronomy
       private
 
       # Sends a batch of events to the Langfuse ingestion endpoint.
+      # The Net::HTTP connection is cached and reused across calls to avoid
+      # per-span TCP + TLS handshake overhead (Issue #61).
       # Errors are rescued and ignored to keep the tracer non-disruptive.
       def ingest(events)
         uri = URI.parse("#{@host}/api/public/ingestion")
-        http = Net::HTTP.new(uri.host, uri.port)
-        http.use_ssl = (uri.scheme == "https")
-        http.open_timeout = 3
-        http.read_timeout = 5
         req = Net::HTTP::Post.new(uri.request_uri)
         req["Content-Type"] = "application/json"
         req["Authorization"] = "Basic #{Base64.strict_encode64("#{@public_key}:#{@secret_key}")}"
         req.body = JSON.generate({batch: events})
-        http.request(req)
-      rescue
+
+        @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.
+        @actor.call { @http = nil }
+        warn "[Phronomy::LangfuseTracer] Ingestion failed: #{e.class}: #{e.message}"
+        nil
+      rescue => e
+        warn "[Phronomy::LangfuseTracer] Ingestion failed: #{e.class}: #{e.message}"
         nil
       end
+
+      def build_http(uri)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = (uri.scheme == "https")
+        http.open_timeout = 3
+        http.read_timeout = 5
+        http
+      end
     end
   end
 end

data/lib/phronomy/tracing/null_tracer.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require "ostruct"
-
 module Phronomy
   module Tracing
     # No-op tracer used as the default. All calls succeed silently.
@@ -10,8 +8,13 @@ module Phronomy
     #
     #   Phronomy.configure { |c| c.tracer = MyRealTracer.new }
     class NullTracer < Base
+      # Internal value object for span handles returned by #start_span.
+      # Uses Struct (not OpenStruct) so that unknown attribute access raises NoMethodError.
+      SpanStruct = Struct.new(:name)
+      private_constant :SpanStruct
+
       # Returns a minimal span object with the given name.
-      def start_span(name, **) = OpenStruct.new(name: name)
+      def start_span(name, **) = SpanStruct.new(name)
 
       # Does nothing.
       def finish_span(span, **) = nil