phronomy 0.1.2 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4bd9ee98ca8c05a22a5488a6996edb95dcffc26d14b1af92d6551bb24b66a530
-  data.tar.gz: 14967148ee9764e8502ba8b45d28aa1640f9a086b80ac1a49d9bab3c228a3a70
+  metadata.gz: 04a7eceda662bfc638c3ec07ac161299b2bb08863e18e9ba03e7a3226165a921
+  data.tar.gz: 9938ace6e4a7250c08f733339af4de14c7d9ff62ff7c52a27eb954c0700d18f4
 SHA512:
-  metadata.gz: b005dd5bac44045180bdbf9945c773155e27ee95d69c90b35e3864d01685d831fcd3617762b16871fc637efc86daca27224dda7040e9ef50120675fd7f18b986
-  data.tar.gz: 2732036e9ed83a86eb75b2e3b55d0a2ccce53b65e354967c1220f1f98b1fb84d09ad42c82673d415dba263a698453827551fe27831e1278252d675e271a67369
+  metadata.gz: 1dc032c438a407a751b5c74fd76d172796e852a3add651c1ca6bb210991d20305a1cc609fe157e48026293084943714569219d359794c9bc7fde0dc396ed16d1
+  data.tar.gz: c1b52dcfa5196b92b72641f8d980856e5e827d61ff0e8afc61f5664f0556e0dbb0b047a7755d2f5f148525774c885ead4319510c32d7f2699fb4601c38d12ecd

data/lib/phronomy/agent/base.rb

@@ -453,9 +453,10 @@ module Phronomy
 
         chat = build_chat
         user_message = extract_message(input)
+        budget = build_token_budget
 
         # Assemble context via Assembler (same as invoke_once).
-        assembler = Context::Assembler.new(budget: build_token_budget)
+        assembler = Context::Assembler.new(budget: budget)
         system_msg = build_instructions(input)
         assembler.add_instruction(system_msg) if system_msg
 
@@ -467,7 +468,33 @@ module Phronomy
 
         if memory && thread_id
           msgs = load_from_memory(memory, thread_id: thread_id, query: user_message)
-          assembler.add_messages(msgs)
+          message_elements = build_message_elements(msgs)
+
+          # Run on_trim: app may call ctx.remove(seqs) to drop messages this turn.
+          if (trim_cb = self.class._on_trim_callback)
+            trim_ctx = Context::TrimContext.new(message_elements: message_elements, budget: budget)
+            trim_cb.call(trim_ctx)
+            message_elements = trim_ctx.message_elements
+          end
+
+          # Run on_compaction_trigger → on_compact pipeline before calling the LLM.
+          if (trigger_cb = self.class._on_compaction_trigger_callback)
+            trigger_ctx = Context::TriggerContext.new(message_elements: message_elements, budget: budget)
+            if trigger_cb.call(trigger_ctx)
+              if (compact_cb = self.class._on_compact_callback)
+                compact_ctx = Context::CompactionContext.new(
+                  message_elements: message_elements,
+                  budget: budget,
+                  thread_id: thread_id,
+                  memory: memory
+                )
+                compact_cb.call(compact_ctx)
+                message_elements = build_message_elements(compact_ctx.result_messages)
+              end
+            end
+          end
+
+          assembler.add_messages(message_elements.map { |e| e[:message] })
         end
 
         context = assembler.build

data/lib/phronomy/agent/handoff.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "securerandom"
+
 module Phronomy
   module Agent
     # Represents a transfer edge from one agent to another.
@@ -25,6 +27,8 @@ module Phronomy
         klass_name = target_agent.class.name&.split("::")&.last || "Agent"
         @tool_name = "transfer_to_#{snake_case(klass_name)}"
         @description = description || "Transfer the conversation to #{klass_name}."
+        # Use a UUID so that two handoffs targeting the same class remain distinct.
+        @uuid = SecureRandom.uuid
       end
 
       # Builds an anonymous Phronomy::Tool::Base subclass for this handoff.
@@ -43,7 +47,7 @@ module Phronomy
       # The sentinel string embedded in the tool result.
       # @return [String]
       def sentinel
-        "#{SENTINEL_PREFIX}:#{target_agent.class.name}"
+        "#{SENTINEL_PREFIX}:#{target_agent.class.name}:#{@uuid}"
       end
 
       private

data/lib/phronomy/agent/react_agent.rb

@@ -28,13 +28,17 @@ module Phronomy
           messages = initial_messages.dup
           user_asked = false
           total_usage = Phronomy::TokenUsage.zero
+          iterations_exhausted = true
 
           max_iter.times do
             response = step(messages, input, user_asked: user_asked, config: config)
             user_asked = true
             messages = response[:messages]
             total_usage += response[:usage]
-            break if response[:done]
+            if response[:done]
+              iterations_exhausted = false
+              break
+            end
           end
 
           save_to_memory(memory, thread_id: thread_id, messages: messages) if memory && thread_id
@@ -44,7 +48,7 @@ module Phronomy
           # Run output guardrails before returning to the caller.
           run_output_guardrails!(output)
 
-          result = {output: output, messages: messages, usage: total_usage}
+          result = {output: output, messages: messages, usage: total_usage, iterations_exhausted: iterations_exhausted}
           [result, total_usage]
         end
       end
@@ -74,13 +78,17 @@ module Phronomy
         messages = initial_messages.dup
         user_asked = false
         total_usage = Phronomy::TokenUsage.zero
+        iterations_exhausted = true
 
         max_iter.times do
           response = stream_step(messages, input, user_asked: user_asked, config: config, &block)
           user_asked = true
           messages = response[:messages]
           total_usage += response[:usage]
-          break if response[:done]
+          if response[:done]
+            iterations_exhausted = false
+            break
+          end
         end
 
         save_to_memory(memory, thread_id: thread_id, messages: messages) if memory && thread_id
@@ -88,7 +96,7 @@ module Phronomy
         output = messages.last&.content
         run_output_guardrails!(output)
 
-        result = {output: output, messages: messages, usage: total_usage}
+        result = {output: output, messages: messages, usage: total_usage, iterations_exhausted: iterations_exhausted}
         block.call(StreamEvent.new(type: :done, payload: result))
         result
       rescue => e

data/lib/phronomy/agent/runner.rb

@@ -52,14 +52,16 @@ module Phronomy
         handoffs_taken = 0
 
         loop do
-          result = current.invoke(input, config: config)
-          target = find_handoff_target(result[:messages])
-          return result.merge(agent: current) unless target
-
+          # Check before invoking so we raise after exactly MAX_HANDOFFS handoffs,
+          # not after MAX_HANDOFFS + 1 LLM calls.
           if handoffs_taken >= MAX_HANDOFFS
             raise Phronomy::HandoffError, "Exceeded maximum handoffs (#{MAX_HANDOFFS})"
           end
 
+          result = current.invoke(input, config: config)
+          target = find_handoff_target(result[:messages])
+          return result.merge(agent: current) unless target
+
           current = target
           handoffs_taken += 1
         end

data/lib/phronomy/configuration.rb

@@ -42,11 +42,17 @@ module Phronomy
     # Recursion limit for graph execution (default: 25)
     attr_accessor :recursion_limit
 
+    # When true (default), user input and LLM output are recorded in trace spans.
+    # Set to false in privacy-sensitive environments to prevent PII from reaching
+    # the tracing backend (OTel, Langfuse, etc.).
+    attr_accessor :trace_pii
+
     def initialize
       @recursion_limit = 25
       @tracer = Phronomy::Tracing::NullTracer.new
       @memory_async = false
       @memory_job_queue = :default
+      @trace_pii = true
     end
   end
 end

data/lib/phronomy/context/token_estimator.rb

@@ -23,13 +23,29 @@ module Phronomy
     #   Phronomy::Context::TokenEstimator.tokenizer = nil
     module TokenEstimator
       @tokenizer = nil
+      @tokenizer_mutex = Mutex.new
 
       class << self
         # Replace the built-in heuristic with a callable that takes a String
         # and returns an Integer token count.  Set to nil to restore the default.
         #
+        # @note This is a process-wide setting. Set it once at application startup.
+        #   In tests, call +TokenEstimator.reset_tokenizer!+ after each test to
+        #   prevent cross-test contamination.
         # @param callable [#call, nil]
-        attr_accessor :tokenizer
+        def tokenizer=(callable)
+          @tokenizer_mutex.synchronize { @tokenizer = callable }
+        end
+
+        # @return [#call, nil]
+        def tokenizer
+          @tokenizer_mutex.synchronize { @tokenizer }
+        end
+
+        # Resets the tokenizer to the built-in heuristic. Intended for test isolation.
+        def reset_tokenizer!
+          @tokenizer_mutex.synchronize { @tokenizer = nil }
+        end
 
         # Estimate the number of tokens for the given input.
         #
@@ -37,9 +53,10 @@ module Phronomy
         #   or an Array of message-like objects (each must respond to #content).
         # @return [Integer] estimated token count (>= 0)
         def estimate(input)
+          tok = @tokenizer_mutex.synchronize { @tokenizer }
           case input
           when String
-            @tokenizer ? @tokenizer.call(input) : (input.length / 4.0).ceil
+            tok ? tok.call(input) : (input.length / 4.0).ceil
           when Array
             input.sum { |m| estimate(m.content.to_s) }
           else

data/lib/phronomy/eval/eval_result.rb

@@ -4,16 +4,26 @@ module Phronomy
   module Eval
     # An immutable record holding the outcome of evaluating one EvalCase.
     #
-    # @!attribute eval_case [EvalCase]  the original sample
-    # @!attribute actual    [String]    the callable's output
-    # @!attribute score     [Float]     scorer-assigned value in [0.0, 1.0]
-    # @!attribute usage     [Phronomy::TokenUsage, nil]
+    # @!attribute eval_case  [EvalCase]  the original sample
+    # @!attribute actual     [String]    the callable's output
+    # @!attribute score      [Float]     scorer-assigned value in [0.0, 1.0]
+    # @!attribute usage      [Phronomy::TokenUsage, nil]
     # @!attribute latency_ms [Integer]  wall-clock time of the callable in ms
-    EvalResult = Data.define(:eval_case, :actual, :score, :usage, :latency_ms) do
+    # @!attribute error      [Exception, nil] set when the scorer raised an exception
+    EvalResult = Data.define(:eval_case, :actual, :score, :usage, :latency_ms, :error) do
+      def initialize(eval_case:, actual:, score:, usage:, latency_ms:, error: nil)
+        super
+      end
+
       # Returns true when the scorer assigned a perfect score of 1.0.
       def pass?
         score >= 1.0
       end
+
+      # Returns true when the scorer raised an exception.
+      def scorer_error?
+        !error.nil?
+      end
     end
   end
 end

data/lib/phronomy/eval/runner.rb

@@ -32,9 +32,9 @@ module Phronomy
           latency_ms = Process.clock_gettime(Process::CLOCK_MONOTONIC, :millisecond) - t0
 
           actual, usage = extract(result)
-          score = @scorer.score(actual: actual, expected: eval_case.expected, input: eval_case.input)
+          score, score_error = score_safely(@scorer, actual: actual, expected: eval_case.expected, input: eval_case.input)
 
-          EvalResult.new(eval_case: eval_case, actual: actual, score: score, usage: usage, latency_ms: latency_ms)
+          EvalResult.new(eval_case: eval_case, actual: actual, score: score, usage: usage, latency_ms: latency_ms, error: score_error)
         end
       end
 
@@ -48,6 +48,13 @@ module Phronomy
           [result.to_s, nil]
         end
       end
+
+      # Calls the scorer and returns [score, error]. On failure, returns [0.0, exception].
+      def score_safely(scorer, **kwargs)
+        [scorer.score(**kwargs), nil]
+      rescue => e
+        [0.0, e]
+      end
     end
   end
 end

data/lib/phronomy/eval/scorer/llm_judge.rb

@@ -34,17 +34,22 @@ module Phronomy
 
         # @param model           [String]  RubyLLM model identifier
         # @param prompt_template [String]  format string with %<input>s, %<expected>s, %<actual>s
-        def initialize(model:, prompt_template: DEFAULT_PROMPT)
+        # @param raise_on_error  [Boolean] when true, re-raises scoring exceptions instead of
+        #   returning 0.0. Use this in batch eval pipelines where silent failures are unacceptable.
+        def initialize(model:, prompt_template: DEFAULT_PROMPT, raise_on_error: false)
           @model = model
           @prompt_template = prompt_template
+          @raise_on_error = raise_on_error
         end
 
-        # @return [Float] score in [0.0, 1.0]; 0.0 on any error
+        # @return [Float] score in [0.0, 1.0]; 0.0 on error when raise_on_error is false
         def score(actual:, expected:, input: nil)
           prompt = format(@prompt_template, input: input.to_s, expected: expected.to_s, actual: actual.to_s)
           response = RubyLLM.chat(model: @model).ask(prompt)
           response.content.to_s.strip.scan(/-?\d+\.?\d*/).first.to_f.clamp(0.0, 1.0)
         rescue => e
+          raise if @raise_on_error
+
           warn "[LlmJudge] Scoring failed: #{e.message}"
           0.0
         end

data/lib/phronomy/graph/parallel_node.rb

@@ -64,36 +64,47 @@ module Phronomy
       def call(state)
         threads = @branches.map { |branch| Thread.new { branch.call(state) } }
         deadline = @timeout ? (Process.clock_gettime(Process::CLOCK_MONOTONIC) + @timeout) : nil
+        state_class = state.class
 
         if @on_error == :best_effort
-          gather_best_effort(threads, deadline)
+          gather_best_effort(threads, deadline, state_class)
         else
-          gather_raise(threads, deadline)
+          gather_raise(threads, deadline, state_class)
         end
       end
 
       private
 
       # Joins all threads, enforcing the deadline. Re-raises branch exceptions.
-      def gather_raise(threads, deadline)
+      def gather_raise(threads, deadline, state_class)
         if deadline
           threads.each do |t|
             remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
             next if t.join([remaining, 0].max)
 
             # Thread did not finish within the time limit.
-            threads.each(&:kill)
+            # Use Thread#raise instead of Thread#kill so that ensure blocks in
+            # branches (DB connection return, Mutex release, etc.) are executed.
+            timeout_error = Phronomy::Graph::TimeoutError.new(
+              "parallel branch timed out after #{@timeout}s"
+            )
+            threads.each { |thr| thr.raise(timeout_error) unless thr.stop? }
+            threads.each do |thr|
+              thr.join(0.1)
+            rescue
+              nil
+            end
             raise Phronomy::Graph::TimeoutError,
               "parallel branch timed out after #{@timeout}s"
           end
         end
 
         # All threads are done. Thread#value re-raises any stored exception.
-        merge_results(threads.map(&:value))
+        merge_results(threads.map(&:value), state_class)
       end
 
       # Joins all threads, collecting errors instead of re-raising them.
-      def gather_best_effort(threads, deadline)
+      def gather_best_effort(threads, deadline, state_class)
         errors = []
         results = threads.map do |t|
           if deadline
@@ -108,7 +119,15 @@ module Phronomy
               next nil
             end
             if joined.nil?
-              t.kill
+              timeout_error = Phronomy::Graph::TimeoutError.new(
+                "branch timed out after #{@timeout}s"
+              )
+              t.raise(timeout_error) unless t.stop?
+              begin
+                t.join(0.1)
+              rescue
+                nil
+              end
               errors << Phronomy::Graph::TimeoutError.new(
                 "branch timed out after #{@timeout}s"
               )
@@ -124,33 +143,49 @@ module Phronomy
           end
         end
 
-        merged = merge_results(results) || {}
+        merged = merge_results(results, state_class) || {}
         merged[:parallel_errors] = errors unless errors.empty?
         merged.empty? ? nil : merged
       end
 
       # Merges an Array of per-branch result Hashes (nils are skipped).
-      def merge_results(results)
+      # Field merge policy is determined from the State class field declarations:
+      #   :replace fields  — last-write-wins (rightmost branch wins)
+      #   :append  fields  — all Arrays are concatenated
+      #   :merge   fields  — all Hashes are deep-merged (rightmost wins on conflict)
+      # Unknown / undeclared fields fall back to type-based heuristics.
+      def merge_results(results, state_class = nil)
         merged = results.compact.each_with_object({}) do |result, acc|
           next unless result.is_a?(Hash)
 
           result.each do |key, val|
-            acc[key] = acc.key?(key) ? merge_values(acc[key], val) : val
+            acc[key] = acc.key?(key) ? merge_values(acc[key], val, state_class&.fields&.dig(key, :type)) : val
           end
         end
 
         merged.empty? ? nil : merged
       end
 
-      # Merges two values that share the same state field key across branches.
-      # Arrays are concatenated; Hashes are deep-merged; scalars use last-write-wins.
-      def merge_values(old_val, new_val)
-        if old_val.is_a?(Array) && new_val.is_a?(Array)
-          old_val + new_val
-        elsif old_val.is_a?(Hash) && new_val.is_a?(Hash)
-          old_val.merge(new_val)
-        else
+      # Merges two values for the same state field key across branches.
+      # Uses the declared field policy when available, otherwise falls back to
+      # type-based heuristics (Array → concat, Hash → deep-merge, scalar → last-write-wins).
+      def merge_values(old_val, new_val, policy = nil)
+        case policy
+        when :append
+          (old_val.is_a?(Array) && new_val.is_a?(Array)) ? old_val + new_val : new_val
+        when :merge
+          (old_val.is_a?(Hash) && new_val.is_a?(Hash)) ? old_val.merge(new_val) : new_val
+        when :replace
           new_val
+        else
+          # Unknown field or no State class: fall back to type-based heuristic.
+          if old_val.is_a?(Array) && new_val.is_a?(Array)
+            old_val + new_val
+          elsif old_val.is_a?(Hash) && new_val.is_a?(Hash)
+            old_val.merge(new_val)
+          else
+            new_val
+          end
         end
       end
     end

data/lib/phronomy/graph/state_graph.rb

@@ -125,6 +125,11 @@ module Phronomy
       #   to use for this compiled graph, overriding the global default.
       # @return [CompiledGraph]
       def compile(state_store: nil)
+        if @entry_point.nil? && @nodes.size > 1
+          raise ArgumentError,
+            "set_entry_point was not called; call set_entry_point(:node_name) " \
+            "before compile when the graph has multiple nodes"
+        end
         CompiledGraph.new(
           state_class: @state_class,
           nodes: @nodes,

data/lib/phronomy/guardrail/builtin/prompt_injection_detector.rb

@@ -9,6 +9,11 @@ module Phronomy
       # {Phronomy::GuardrailError} when any pattern is found in the input string.
       # Additional patterns can be supplied via the +additional_patterns:+ argument.
       #
+      # **Limitations**: the built-in patterns cover well-known English and Japanese
+      # phrasings. Obfuscated, Base64-encoded, or novel injection phrasing may not
+      # be detected. For higher-assurance use cases, combine this guardrail with an
+      # LLM-based classifier.
+      #
       # @example
       #   agent.add_input_guardrail(
       #     Phronomy::Guardrail::Builtin::PromptInjectionDetector.new
@@ -21,6 +26,7 @@ module Phronomy
       class PromptInjectionDetector < InputGuardrail
         # Default patterns that signal a prompt injection attempt.
         DEFAULT_PATTERNS = [
+          # --- English patterns ---
           /ignore\s+(all\s+)?(previous|prior|above)\s+(instructions?|rules?|prompts?)/i,
           /disregard\s+(all\s+)?(previous|prior|above)\s+(instructions?|rules?|prompts?)/i,
           /forget\s+(all\s+)?(previous|prior|above)\s+(instructions?|rules?|prompts?)/i,
@@ -30,7 +36,15 @@ module Phronomy
           /\bpretend\s+(?:you\s+are|to\s+be)\b/i,
           /\bjailbreak\b/i,
           /\bdan\s*mode\b/i,
-          /\bdev(?:eloper)?\s*mode\b/i
+          /\bdev(?:eloper)?\s*mode\b/i,
+          # --- Japanese patterns ---
+          /以前の(指示|ルール|プロンプト)を無視/,
+          /指示を無視して/,
+          /ルールを無視して/,
+          /あなたは今(から)?(?!助けて)/,
+          /システムプロンプト/,
+          /制約(を|から)無視/,
+          /制限(を|から)解除/
         ].freeze
 
         # @param additional_patterns [Array<Regexp>] extra patterns to check in addition

data/lib/phronomy/memory/conversation_manager.rb

@@ -48,6 +48,7 @@ module Phronomy
         @retrieval = retrieval
         @compression = compression
         @ttl = ttl
+        @append_mutex = Mutex.new
       end
 
       # Load conversation messages for a thread, applying retrieval selection.
@@ -66,7 +67,7 @@ module Phronomy
       def load(thread_id:, query: nil)
         @storage.purge_older_than(thread_id: thread_id, older_than: Time.now - @ttl) if @ttl
         messages = reconstruct(thread_id)
-        @retrieval.select(messages, query: query)
+        @retrieval.select(messages, query: query, thread_id: thread_id)
       end
 
       # Persist new messages for a thread and optionally apply compression.
@@ -126,10 +127,14 @@ module Phronomy
       # Append messages that are new since the last save to the raw history.
       # Messages are append-only; existing raw entries are never modified.
       def append_new_messages(thread_id:, messages:)
-        raw = @storage.load_raw(thread_id: thread_id)
-        starting_seq = raw.length
-        new_messages = messages[starting_seq..]
-        @storage.append_raw(thread_id: thread_id, messages: new_messages, starting_seq: starting_seq) if new_messages&.any?
+        # Synchronize load + append to prevent seq number collisions when two
+        # threads save the same thread_id concurrently.
+        @append_mutex.synchronize do
+          raw = @storage.load_raw(thread_id: thread_id)
+          starting_seq = raw.length
+          new_messages = messages[starting_seq..]
+          @storage.append_raw(thread_id: thread_id, messages: new_messages, starting_seq: starting_seq) if new_messages&.any?
+        end
       end
 
       # Apply the configured compression strategy and persist the result.
@@ -183,14 +188,16 @@ module Phronomy
         summary_msgs + uncompacted
       end
 
+      # Immutable value object used as a summary placeholder in reconstructed context.
+      SummaryMessage = Data.define(:role, :content)
+
       def summary_message(text)
-        require "ostruct"
         content = <<~CONTEXT.chomp
           <context type="summary" source="memory" trusted="false">
           #{text}
           </context>
         CONTEXT
-        OpenStruct.new(role: :system, content: content)
+        SummaryMessage.new(role: :system, content: content)
       end
     end
   end

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

@@ -9,10 +9,11 @@ module Phronomy
       class Base
         # Select messages to inject into the context from a full chronological history.
         #
-        # @param messages [Array]        full history in chronological order
-        # @param query    [String, nil]  current user input for query-aware retrieval
+        # @param messages  [Array]        full history in chronological order
+        # @param query     [String, nil]  current user input for query-aware retrieval
+        # @param thread_id [String, nil]  active thread identifier for scoped retrieval
         # @return [Array] subset of messages in chronological order
-        def select(messages, query: nil)
+        def select(messages, query: nil, thread_id: nil)
           raise NotImplementedError, "#{self.class}#select is not implemented"
         end
       end

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

@@ -29,15 +29,16 @@ module Phronomy
         # Merge results from all child retrievals, deduplicating by role+content.
         # System messages are sorted to the front; others preserve insertion order.
         #
-        # @param messages [Array]       full chronological history
-        # @param query    [String, nil] forwarded to each child retrieval
+        # @param messages  [Array]        full chronological history
+        # @param query     [String, nil]  forwarded to each child retrieval
+        # @param thread_id [String, nil]  forwarded to each child retrieval
         # @return [Array]
-        def select(messages, query: nil)
+        def select(messages, query: nil, thread_id: nil)
           all_messages = []
           seen = {}
 
           @sources.each do |source|
-            source[:retrieval].select(messages, query: query).each do |msg|
+            source[:retrieval].select(messages, query: query, thread_id: thread_id).each do |msg|
               key = "#{msg.role}:#{msg.content}"
               next if seen[key]
 

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

@@ -22,10 +22,11 @@ module Phronomy
 
         # Returns the last k*2 messages from the history.
         #
-        # @param messages [Array]       full chronological history
-        # @param query    [String, nil] unused for recency-based retrieval
+        # @param messages  [Array]        full chronological history
+        # @param query     [String, nil]  unused for recency-based retrieval
+        # @param thread_id [String, nil]  unused for recency-based retrieval
         # @return [Array]
-        def select(messages, query: nil)
+        def select(messages, query: nil, thread_id: nil)
           messages.last(@k * 2)
         end
       end

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

@@ -18,12 +18,17 @@ module Phronomy
         # @param store      [Phronomy::VectorStore::Base]  vector store (default InMemory)
         # @param embeddings [Phronomy::Embeddings::Base]   embeddings adapter
         # @param k          [Integer]                      number of messages to retrieve
-        def initialize(embeddings:, store: nil, k: 10)
+        # @param max_index_size [Integer, nil] maximum number of entries kept in the
+        #   local index. When nil, the index grows unboundedly. When exceeded, the
+        #   oldest entries (by insertion order) are evicted.
+        def initialize(embeddings:, store: nil, k: 10, max_index_size: nil)
           @store = store || Phronomy::VectorStore::InMemory.new
           @embeddings = embeddings
           @k = k
-          @index = {}   # id => message
+          @index = {}   # id => message  (insertion-ordered via Ruby Hash)
           @counter = 0
+          @max_index_size = max_index_size
+          @mutex = Mutex.new
         end
 
         # Index a new batch of messages so they are searchable on future #select calls.
@@ -33,11 +38,14 @@ module Phronomy
         # @param messages  [Array]
         def index(thread_id:, messages:)
           messages.each do |msg|
-            id = "#{thread_id}:#{@counter}"
-            @counter += 1
             embedding = @embeddings.embed(msg.content.to_s)
-            @store.add(id: id, embedding: embedding, metadata: {thread_id: thread_id, message: msg})
-            @index[id] = msg
+            @mutex.synchronize do
+              id = "#{thread_id}:#{@counter}"
+              @counter += 1
+              @store.add(id: id, embedding: embedding, metadata: {thread_id: thread_id, message: msg})
+              @index[id] = msg
+              evict_oldest! if @max_index_size && @index.size > @max_index_size
+            end
           end
         end
 
@@ -45,24 +53,27 @@ module Phronomy
         #
         # @param thread_id [String]
         def clear_index(thread_id:)
-          ids = @index.select { |id, _| id.start_with?("#{thread_id}:") }.keys
-          ids.each do |id|
-            @index.delete(id)
-            @store.remove(id: id)
+          @mutex.synchronize do
+            ids = @index.keys.select { |id| id.start_with?("#{thread_id}:") }
+            ids.each do |id|
+              @index.delete(id)
+              @store.remove(id: id)
+            end
           end
         end
 
         # Return semantically relevant messages, or recent messages when query is nil.
         #
-        # @param messages [Array]       full history (used as fallback when query is nil)
-        # @param query    [String, nil] current user input for semantic search
+        # @param messages   [Array]        full history (used as fallback when query is nil)
+        # @param query      [String, nil]  current user input for semantic search
+        # @param thread_id  [String, nil]  when provided, results are filtered to this thread
         # @return [Array]
-        def select(messages, query: nil)
+        def select(messages, query: nil, thread_id: nil)
           if query && !query.strip.empty?
             query_embedding = @embeddings.embed(query)
             results = @store.search(query_embedding: query_embedding, k: @k * 3)
             results
-              .select { |r| r[:metadata][:thread_id] == extract_thread_from_results(r, messages) }
+              .select { |r| thread_id.nil? || r[:metadata][:thread_id] == thread_id }
               .first(@k)
               .map { |r| r[:metadata][:message] }
           else
@@ -72,8 +83,14 @@ module Phronomy
 
         private
 
-        def extract_thread_from_results(result, _messages)
-          result[:metadata][:thread_id]
+        # Evicts the oldest index entry to enforce max_index_size.
+        # Must be called inside @mutex.synchronize.
+        def evict_oldest!
+          oldest_id = @index.keys.first
+          return unless oldest_id
+
+          @index.delete(oldest_id)
+          @store.remove(id: oldest_id)
         end
       end
     end

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

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require "json"
-require "ostruct"
 
 module Phronomy
   module Memory
@@ -38,6 +37,10 @@ module Phronomy
       #     compaction_model_class: PhronomyCompaction
       #   )
       #   manager = Phronomy::Memory::ConversationManager.new(storage: storage, ...)
+      # Internal value object representing a loaded message record.
+      MessageStruct = Data.define(:role, :content, :tool_calls, :model_id)
+      private_constant :MessageStruct
+
       class ActiveRecord < Base
         # @param model_class            [Class]      AR model for the legacy load/save interface
         # @param raw_model_class        [Class, nil] AR model for raw message storage
@@ -55,7 +58,7 @@ module Phronomy
         # Load all messages for a thread, ordered by creation time.
         #
         # @param thread_id [String]
-        # @return [Array<OpenStruct>]
+        # @return [Array<MessageStruct>]
         def load(thread_id:)
           records = @model_class.where(thread_id: thread_id).order(:created_at).to_a
           records.map { |r| to_message_struct(r) }
@@ -201,7 +204,7 @@ module Phronomy
               parsed
             end
           end
-          OpenStruct.new(
+          MessageStruct.new(
             role: record.role.to_sym,
             content: record.content,
             tool_calls: tool_calls,

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

@@ -11,6 +11,7 @@ module Phronomy
       #   manager = Phronomy::Memory::ConversationManager.new(storage: storage, ...)
       class InMemory < Base
         def initialize
+          @mutex = Mutex.new
           @store = {}
           @raw_store = {}       # thread_id => [{seq:, message:}, ...]
           @compaction_store = {} # thread_id => [{start_seq:, end_seq:, summary_text:}, ...]
@@ -23,20 +24,22 @@ module Phronomy
         # @param thread_id [String]
         # @return [Array]
         def load(thread_id:)
-          (@store[thread_id] || []).dup
+          @mutex.synchronize { (@store[thread_id] || []).dup }
         end
 
         # @param thread_id [String]
         # @param messages  [Array]
         def save(thread_id:, messages:)
-          @store[thread_id] = messages.dup
+          @mutex.synchronize { @store[thread_id] = messages.dup }
         end
 
         # @param thread_id [String]
         def clear(thread_id:)
-          @store.delete(thread_id)
-          clear_raw(thread_id: thread_id)
-          clear_compactions(thread_id: thread_id)
+          @mutex.synchronize do
+            @store.delete(thread_id)
+            @raw_store.delete(thread_id)
+            @compaction_store.delete(thread_id)
+          end
         end
 
         # -----------------------------------------------------------------------
@@ -48,21 +51,23 @@ module Phronomy
         # @param starting_seq [Integer]
         def append_raw(thread_id:, messages:, starting_seq:)
           now = Time.now
-          @raw_store[thread_id] ||= []
-          messages.each_with_index do |msg, i|
-            @raw_store[thread_id] << {seq: starting_seq + i, message: msg, recorded_at: now}
+          @mutex.synchronize do
+            @raw_store[thread_id] ||= []
+            messages.each_with_index do |msg, i|
+              @raw_store[thread_id] << {seq: starting_seq + i, message: msg, recorded_at: now}
+            end
           end
         end
 
         # @param thread_id [String]
         # @return [Array<Hash>]
         def load_raw(thread_id:)
-          (@raw_store[thread_id] || []).dup
+          @mutex.synchronize { (@raw_store[thread_id] || []).dup }
         end
 
         # @param thread_id [String]
         def clear_raw(thread_id:)
-          @raw_store.delete(thread_id)
+          @mutex.synchronize { @raw_store.delete(thread_id) }
         end
 
         # -----------------------------------------------------------------------
@@ -74,19 +79,21 @@ module Phronomy
         # @param end_seq      [Integer]
         # @param summary_text [String]
         def save_compaction(thread_id:, start_seq:, end_seq:, summary_text:)
-          @compaction_store[thread_id] ||= []
-          @compaction_store[thread_id] << {start_seq: start_seq, end_seq: end_seq, summary_text: 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}
+          end
         end
 
         # @param thread_id [String]
         # @return [Array<Hash>]
         def load_compactions(thread_id:)
-          (@compaction_store[thread_id] || []).dup
+          @mutex.synchronize { (@compaction_store[thread_id] || []).dup }
         end
 
         # @param thread_id [String]
         def clear_compactions(thread_id:)
-          @compaction_store.delete(thread_id)
+          @mutex.synchronize { @compaction_store.delete(thread_id) }
         end
 
         # Remove raw messages recorded before +older_than+ for this thread.
@@ -94,9 +101,11 @@ module Phronomy
         # @param thread_id  [String]
         # @param older_than [Time]
         def purge_older_than(thread_id:, older_than:)
-          return unless @raw_store[thread_id]
+          @mutex.synchronize do
+            next unless @raw_store[thread_id]
 
-          @raw_store[thread_id].reject! { |entry| entry[:recorded_at] && entry[:recorded_at] < older_than }
+            @raw_store[thread_id].reject! { |entry| entry[:recorded_at] && entry[:recorded_at] < older_than }
+          end
         end
       end
     end

data/lib/phronomy/rails/agent_job.rb

@@ -25,6 +25,8 @@ module Phronomy
     class AgentJob < ::ActiveJob::Base
       # @param agent_class_name [String]
       #   The constantize-able class name of the agent to run (e.g. "MyAgent").
+      #   **Security**: only classes that are subclasses of +Phronomy::Agent::Base+
+      #   are accepted. Never pass a value derived from user-controlled input.
       # @param input [String, Hash]
       #   User input forwarded unchanged to the agent's +#stream+ method.
       # @param channel [String]
@@ -35,21 +37,36 @@ module Phronomy
       #   Configuration forwarded to the agent's +#stream+ call. Both symbol and
       #   string keys are accepted; all keys are converted to symbols before use.
       def perform(agent_class_name, input, channel:, stream:, config: {})
-        agent = Object.const_get(agent_class_name).new
+        klass = resolve_agent_class!(agent_class_name)
+        agent = klass.new
         agent.stream(input, config: config.transform_keys(&:to_sym)) do |event|
           ActionCable.server.broadcast(stream, build_payload(event))
         end
       rescue => e
-        ActionCable.server.broadcast(stream, {type: "error", message: e.message})
+        ::Rails.logger.error("[Phronomy::Rails::AgentJob] agent error (#{e.class}): #{e.message}")
+        ActionCable.server.broadcast(stream, {type: "error", message: "An error occurred while processing your request."})
       end
 
       private
 
+      # Resolves and validates the agent class name.
+      # Raises ArgumentError when the name does not resolve to a subclass of
+      # Phronomy::Agent::Base, preventing arbitrary class instantiation.
+      def resolve_agent_class!(class_name)
+        klass = Object.const_get(class_name.to_s)
+        unless klass.is_a?(Class) && klass < Phronomy::Agent::Base
+          raise ArgumentError, "#{class_name.inspect} is not a Phronomy::Agent::Base subclass"
+        end
+        klass
+      rescue NameError
+        raise ArgumentError, "Unknown agent class: #{class_name.inspect}"
+      end
+
       def build_payload(event)
         case event.type
         when :token then {type: "token", content: event.payload[:content]}
         when :done then {type: "done", output: event.payload[:output]}
-        when :error then {type: "error", message: event.payload[:error]&.message}
+        when :error then {type: "error", message: "An error occurred while processing your request."}
         else {type: event.type.to_s}
         end
       end

data/lib/phronomy/runnable.rb

@@ -28,7 +28,10 @@ module Phronomy
     # @example
     #   trace("my_chain", input: input) { [invoke(input), nil] }
     def trace(name, input: nil, **meta, &block)
-      Phronomy.configuration.tracer.trace(name, input: input, **meta, &block)
+      # Redact user input from spans when trace_pii is disabled to prevent
+      # accidental PII transmission to external tracing backends.
+      traced_input = Phronomy.configuration.trace_pii ? input : "[REDACTED]"
+      Phronomy.configuration.tracer.trace(name, input: traced_input, **meta, &block)
     end
   end
 end

data/lib/phronomy/state_store/active_record.rb

@@ -43,9 +43,13 @@ module Phronomy
       def save(state)
         json = serialize_state(state)
         payload = @encryptor ? @encryptor.encrypt(json) : json
-        record = @model_class.find_or_initialize_by(thread_id: state.thread_id)
-        record.state_json = payload
-        record.save!
+        # Use upsert to avoid a race condition where two concurrent saves for the
+        # same thread_id would both see "no record" and collide on the unique index.
+        @model_class.upsert(
+          {thread_id: state.thread_id, state_json: payload},
+          unique_by: :thread_id,
+          update_only: [:state_json]
+        )
         self
       end
 

data/lib/phronomy/state_store/base.rb

@@ -61,9 +61,23 @@ module Phronomy
       end
 
       # Resolves and validates a state class name.
-      # Raises ArgumentError if the name does not resolve to a class that
-      # includes Phronomy::Graph::State, preventing unsafe deserialization.
+      # When a registry has been configured via +Phronomy::Graph.register_state_class+,
+      # 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.
       def safe_state_class(class_name)
+        registry = Phronomy::Graph.state_class_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."
+          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}"

data/lib/phronomy/tool/base.rb

@@ -193,6 +193,11 @@ module Phronomy
         end
       end
 
+      # Instance method accessor — delegates to the class-level flag.
+      def requires_approval
+        self.class.requires_approval
+      end
+
       # Instance method for requires_approval? (convenience accessor).
       def requires_approval?
         self.class.requires_approval
@@ -276,11 +281,15 @@ module Phronomy
 
         self.class.parameters.each do |name, param|
           value = normalized[name]
-          next if value.nil? && !param.required
+          if value.nil?
+            # Return a descriptive error for missing required params so the LLM
+            # can self-correct on the next turn.
+            return [nil, "required parameter '#{name}' is missing"] if param.required
+            next
+          end
 
           if coerce_mode
             coerced, error = coerce_value(value, param.type)
-            return [nil, error] if error && !coerce_mode
             return [nil, error] if error
             value = coerced
           else

data/lib/phronomy/tool/mcp_tool.rb

@@ -79,12 +79,27 @@ module Phronomy
       # -----------------------------------------------------------------------
 
       # Minimal stdio transport implementing a subset of the MCP JSON-RPC protocol.
-      # Spawns the server command as a child process and communicates line-by-line.
+      # Keeps the child process alive for the lifetime of this transport instance
+      # so that session state (registered resources, tool context, etc.) is preserved
+      # across multiple calls.
       class StdioTransport
         def initialize(command)
           # 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
+          @stdin = nil
+          @stdout = nil
+        end
+
+        # Shut down the child process and close its IO streams.
+        def close
+          @mutex.synchronize do
+            @stdin&.close
+            @stdout&.close
+            @stdin = nil
+            @stdout = nil
+          end
         end
 
         # Retrieve the tool definition from the server using the MCP `tools/list` method.
@@ -108,6 +123,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 server returned error: #{err_msg}"
+          end
           content = response.dig("result", "content")
 
           # MCP content is an array of content blocks; extract text blocks.
@@ -121,12 +140,22 @@ module Phronomy
 
         private
 
-        def rpc_call(method, params)
-          payload = JSON.generate(jsonrpc: "2.0", id: 1, method: method, params: params)
-          stdout, _stderr, status = Open3.capture3(*@command, stdin_data: "#{payload}\n")
-          raise Phronomy::ToolError, "MCP server exited with status #{status.exitstatus}" unless status.success?
+        # Ensure the child process is running, spawning it if necessary.
+        def ensure_started!
+          return if @stdin && !@stdin.closed?
 
-          JSON.parse(stdout.lines.first.to_s)
+          @stdin, @stdout, _stderr, _wait_thr = Open3.popen3(*@command)
+        end
+
+        def rpc_call(method, params)
+          @mutex.synchronize do
+            ensure_started!
+            payload = JSON.generate(jsonrpc: "2.0", id: SecureRandom.uuid, method: method, params: params)
+            @stdin.puts(payload)
+            raw = @stdout.gets
+            raise Phronomy::ToolError, "MCP server closed the connection unexpectedly" if raw.nil?
+            JSON.parse(raw)
+          end
         end
 
         def parse_schema_params(properties)
@@ -153,9 +182,13 @@ module Phronomy
       #     tool_name: "weather_lookup"
       #   )
       class HttpTransport
-        # @param base_url [String] full URL of the MCP endpoint, e.g. "http://localhost:8080/mcp"
-        def initialize(base_url)
+        # @param base_url     [String]  full URL of the MCP endpoint, e.g. "http://localhost:8080/mcp"
+        # @param open_timeout [Integer] TCP connection timeout in seconds (default: 5)
+        # @param read_timeout [Integer] HTTP read timeout in seconds (default: 30)
+        def initialize(base_url, open_timeout: 5, read_timeout: 30)
           @uri = URI.parse(base_url)
+          @open_timeout = open_timeout
+          @read_timeout = read_timeout
         end
 
         # Retrieve the tool definition from the server using MCP `tools/list`.
@@ -192,10 +225,12 @@ module Phronomy
         private
 
         def rpc_call(method, params)
-          payload = JSON.generate(jsonrpc: "2.0", id: 1, method: method, params: params)
+          payload = JSON.generate(jsonrpc: "2.0", id: SecureRandom.uuid, method: method, params: params)
 
           http = Net::HTTP.new(@uri.host, @uri.port)
           http.use_ssl = (@uri.scheme == "https")
+          http.open_timeout = @open_timeout
+          http.read_timeout = @read_timeout
 
           path = @uri.path.empty? ? "/" : @uri.path
           path = "#{path}?#{@uri.query}" if @uri.query

data/lib/phronomy/tracing/langfuse_tracer.rb

@@ -83,6 +83,8 @@ module Phronomy
         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}")}"

data/lib/phronomy/trust_pipeline.rb

@@ -82,6 +82,8 @@ module Phronomy
       @review_agent_class = review_agent
       @threshold = confidence_threshold.to_f
       @max_iterations = max_iterations.to_i
+      @graph_mutex = Mutex.new
+      @compiled_graph = nil
     end
 
     # Run the pipeline.
@@ -90,7 +92,7 @@ module Phronomy
     # @param config [Hash]   forwarded to the underlying agents (e.g. thread_id)
     # @return [Result]
     def invoke(input, config: {})
-      app = build_graph.compile
+      app = compiled_graph
       state = app.invoke({input: input}, config: config)
       confidence = combined_confidence(state)
       Result.new(
@@ -109,6 +111,16 @@ module Phronomy
       [(state.self_score || 0.0).to_f, (state.review_score || 0.0).to_f].min
     end
 
+    # Returns the compiled graph, building and caching it on first call.
+    # Thread-safe via double-checked locking.
+    def compiled_graph
+      return @compiled_graph if @compiled_graph
+
+      @graph_mutex.synchronize do
+        @compiled_graph ||= build_graph.compile
+      end
+    end
+
     def build_graph
       draft_agent = @draft_agent_class.new
       review_agent = @review_agent_class.new

data/lib/phronomy/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Phronomy
-  VERSION = "0.1.2"
+  VERSION = "0.1.3"
 end

data/lib/phronomy.rb

@@ -35,6 +35,45 @@ module Phronomy
     end
   end
 
+  # Namespace for graph-related classes (StateGraph, State, ParallelNode, …).
+  # Also serves as the registry for State classes that may be serialized to
+  # external stores (Redis, DB). Call +register_state_class+ at application
+  # startup so that only known classes can be deserialized.
+  module Graph
+    @state_class_registry = nil
+    @registry_mutex = Mutex.new
+
+    class << self
+      # Register one or more State classes that are allowed to be deserialized
+      # by StateStore backends. When at least one class is registered, only
+      # registered classes will be accepted by +StateStore::Base#safe_state_class+.
+      #
+      # Call this once at application startup (e.g. in a Rails initializer).
+      #
+      # @param classes [Array<Class>] classes including Phronomy::Graph::State
+      # @example
+      #   Phronomy::Graph.register_state_class(MyWorkflowState, OtherState)
+      def register_state_class(*classes)
+        @registry_mutex.synchronize do
+          @state_class_registry ||= {}
+          classes.each do |klass|
+            raise ArgumentError, "#{klass.inspect} is not a Class" unless klass.is_a?(Class)
+            @state_class_registry[klass.name] = klass
+          end
+        end
+      end
+
+      # Returns the current registry Hash, or nil when no class has been registered.
+      # @return [Hash{String => Class}, nil]
+      attr_reader :state_class_registry
+
+      # Clears the registry. Primarily used in tests.
+      def reset_state_class_registry!
+        @registry_mutex.synchronize { @state_class_registry = nil }
+      end
+    end
+  end
+
   class << self
     def configuration
       @configuration ||= Configuration.new

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: phronomy
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.3
 platform: ruby
 authors:
 - Raizo T.C.S