phronomy 0.7.0 → 0.8.0

data/lib/phronomy/tool/mcp_tool.rb

@@ -5,7 +5,6 @@ require "net/http"
 require "open3"
 require "securerandom"
 require "shellwords"
-require "timeout"
 require "uri"
 
 module Phronomy
@@ -67,7 +66,7 @@ module Phronomy
 
         def build_tool_class(tool_name, server_uri, tool_def)
           klass = Class.new(McpTool)
-          klass.instance_variable_set(:@mcp_tool_name, tool_name)
+          klass.tool_name(tool_name)
           klass.instance_variable_set(:@mcp_server_uri, server_uri)
 
           # Register description and params from the MCP tool definition.
@@ -118,7 +117,9 @@ module Phronomy
         #   {HttpTransport}. Defaults to 30 seconds.
         # @param env             [Hash, nil] environment variable overrides for the subprocess.
         #   When provided, only these variables are added/overridden; the parent environment
-        #   is still inherited unless explicitly cleared via an empty string value.
+        #   is still inherited. Use +nil+ as a value to unset a variable in the child process
+        #   (e.g. +{ "SECRET" => nil }+). An empty string value (+""+ ) sets the variable to
+        #   an empty string — it does NOT unset it.
         # @param cwd             [String, nil] working directory for the subprocess.
         #   Defaults to the current process's working directory.
         # @param startup_timeout [Numeric, nil] seconds to wait for the server to
@@ -138,6 +139,7 @@ module Phronomy
           @stderr = nil
           @wait_thr = nil
           @stderr_thread = nil
+          @stderr_op = nil
         end
 
         # Shut down the child process and close its IO streams.
@@ -149,10 +151,17 @@ module Phronomy
           @stdout = nil
           @stderr = nil
           stderr_thread = @stderr_thread
+          stderr_op = @stderr_op
           wait_thr = @wait_thr
           @stderr_thread = nil
+          @stderr_op = nil
           @wait_thr = nil
           stderr_thread&.join(1)
+          begin
+            stderr_op&.await(timeout: 1.0)
+          rescue
+            nil
+          end
           wait_thr&.join(5)
         end
 
@@ -209,31 +218,53 @@ module Phronomy
           # 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
+          #
+          # Prefer BlockingAdapterPool when a Runtime is configured so that this
+          # file eventually needs no direct Thread.new (Issue #360). Fall back to
+          # Thread.new when no pool is available (no EventLoop / bare invocation).
+          pool = begin; Phronomy::Runtime.instance&.blocking_io; rescue; nil; end
+          if pool
+            @stderr_op = pool.submit {
+              begin
+                @stderr.read
+              rescue
+                nil
+              end
+            }
+            @stderr_thread = nil
+          else
+            @stderr_thread = Thread.new {
+              begin
+                @stderr.read
+              rescue
+                nil
+              end
+            }
+            @stderr_op = nil
           end
 
           if @startup_timeout
-            Timeout.timeout(@startup_timeout) { @stdout.gets.tap { |line| @stdout.ungetbyte(line) if line } }
+            unless IO.select([@stdout], nil, nil, @startup_timeout)
+              close
+              raise Phronomy::ToolError,
+                "MCP stdio server did not start within #{@startup_timeout} seconds"
+            end
+            line = @stdout.gets
+            @stdout.ungetbyte(line) if line
           end
-        rescue Timeout::Error
-          close
-          raise Phronomy::ToolError,
-            "MCP stdio server did not start within #{@startup_timeout} seconds"
         end
 
         def rpc_call(method, params)
           ensure_started!
           payload = JSON.generate(jsonrpc: "2.0", id: SecureRandom.uuid, method: method, params: params)
           @stdin.puts(payload)
-          raw = Timeout.timeout(@read_timeout) { @stdout.gets }
+          unless IO.select([@stdout], nil, nil, @read_timeout)
+            raise Phronomy::ToolError,
+              "MCP stdio server did not respond within #{@read_timeout} seconds"
+          end
+          raw = @stdout.gets
           raise Phronomy::ToolError, "MCP server closed the connection unexpectedly" if raw.nil?
           JSON.parse(raw)
-        rescue Timeout::Error
-          raise Phronomy::ToolError,
-            "MCP stdio server did not respond within #{@read_timeout} seconds"
         end
 
         def parse_schema_params(properties, required_names: [])

data/lib/phronomy/tool/scope_policy.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Tool
+    # Evaluates whether a tool with a given scope may execute.
+    #
+    # A ScopePolicy is a callable that receives +(tool_class, scope, agent)+ and
+    # returns one of:
+    #   +:allow+   — proceed immediately without an approval gate.
+    #   +:reject+  — block execution; the tool returns a denial message.
+    #   +:approve+ — delegate to the agent's approval handler (if registered);
+    #                when no handler is registered the call is rejected.
+    #
+    # The {Default} instance is used automatically when no custom policy is
+    # configured on an agent.
+    #
+    # @example Custom policy that allows everything
+    #   agent.scope_policy = ->(_tool_class, _scope, _agent) { :allow }
+    #
+    # @example Strict policy that rejects all write scopes
+    #   agent.scope_policy = ->(_tc, scope, _agent) {
+    #     scope == :write ? :reject : :allow
+    #   }
+    class ScopePolicy
+      # Scopes that must go through an approval gate before execution.
+      APPROVAL_REQUIRED_SCOPES = %i[write admin external_network filesystem process external_process].freeze
+
+      # Scopes that are always permitted without approval.
+      ALWAYS_ALLOWED_SCOPES = %i[read_only].freeze
+
+      # Returns +:allow+ for always-allowed scopes, +:approve+ for high-risk
+      # scopes, and +:allow+ for anything else (including +nil+).
+      #
+      # @param _tool_class [Class]
+      # @param scope [Symbol, nil]
+      # @param _agent [Object]
+      # @return [:allow, :approve, :reject]
+      # @api private
+      def call(_tool_class, scope, _agent)
+        return :allow if scope.nil? || ALWAYS_ALLOWED_SCOPES.include?(scope)
+        return :approve if APPROVAL_REQUIRED_SCOPES.include?(scope)
+
+        :allow
+      end
+
+      # Shared singleton used when no custom policy is configured.
+      DEFAULT = new.freeze
+    end
+  end
+end

data/lib/phronomy/tracing/null_tracer.rb

@@ -16,7 +16,9 @@ module Phronomy
       # Returns a minimal span object with the given name.
       def start_span(name, **) = SpanStruct.new(name)
 
-      # Does nothing.
+      # Does nothing. Explicit nil is equivalent to an empty method body; the
+      # mutation "remove nil" is accepted as it does not change observable behaviour.
+      # mutant:disable
       def finish_span(span, **) = nil
     end
   end

data/lib/phronomy/tracing/open_telemetry_tracer.rb

@@ -52,6 +52,40 @@ module Phronomy
         end
         span.finish
       end
+
+      # Overrides Base#trace to use OTel +in_span+, which pushes the span onto
+      # the OTel Context stack while the block runs.  Nested +trace+ calls
+      # automatically inherit the current span as their parent, establishing the
+      # correct parent/child hierarchy in the trace tree.
+      #
+      # @param name [String] span name
+      # @param input [Object, nil] input to record as a span attribute
+      # @param meta [Hash] additional metadata (e.g. task_id, user_id)
+      # @yield [span] the active OTel span
+      # @return [Object] the block's return value
+      # @api private
+      def trace(name, input: nil, **meta)
+        attrs = {}
+        attrs["phronomy.input"] = input.to_s if input
+        meta.each { |k, v| attrs["phronomy.#{k}"] = v.to_s unless v.nil? }
+
+        result = nil
+        @otel_tracer.in_span(name, attributes: attrs) do |span|
+          result, usage = yield span
+          span.set_attribute("phronomy.output", result.to_s) if result
+          if usage
+            span.set_attribute("llm.usage.input_tokens", usage.input)
+            span.set_attribute("llm.usage.output_tokens", usage.output)
+            total = (usage.input || 0) + (usage.output || 0)
+            span.set_attribute("llm.usage.total_tokens", total)
+          end
+        rescue => e
+          span.record_exception(e)
+          span.status = OpenTelemetry::Trace::Status.error(e.message)
+          raise
+        end
+        result
+      end
     end
   end
 end

data/lib/phronomy/vector_store.rb

@@ -4,8 +4,8 @@ module Phronomy
   # Vector store implementations for embedding-based semantic search.
   #
   # Sub-classes are auto-loaded by Zeitwerk:
-  #   Phronomy::VectorStore::Base
-  #   Phronomy::VectorStore::InMemory
+  #   Phronomy::Agent::Context::Knowledge::VectorStore::Base
+  #   Phronomy::Agent::Context::Knowledge::VectorStore::InMemory
   module VectorStore
   end
 end

data/lib/phronomy/version.rb

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

data/lib/phronomy/workflow.rb

@@ -81,12 +81,35 @@ module Phronomy
     # Executes the workflow from the initial state.
     # @param input [Hash] initial context field values
     # @param config [Hash] { thread_id:, recursion_limit:, user_id:, session_id: }
+    # @param invocation_context [Phronomy::InvocationContext, nil] optional first-class context
+    #   object.  When present, +thread_id+, +cancellation_token+, and +deadline+ are
+    #   derived from it (existing +config:+ keys take precedence).  The object is also
+    #   stored in +config[:invocation_context]+ for downstream tracing.
     # @return [Object] final context
     # @api public
-    def invoke(input, config: {})
+    def invoke(input, config: {}, invocation_context: nil)
+      if invocation_context
+        config = _apply_invocation_context(config, invocation_context)
+      end
       @runner.invoke(input, config: config)
     end
 
+    # Invokes this workflow asynchronously and returns a {Phronomy::Task}.
+    #
+    # @param input  [Hash]
+    # @param config [Hash]
+    # @param invocation_context [Phronomy::InvocationContext, nil]
+    # @return [Phronomy::Task]
+    # @api public
+    def invoke_async(input, config: {}, invocation_context: nil)
+      if invocation_context
+        config = _apply_invocation_context(config, invocation_context)
+      end
+      Phronomy::Runtime.instance.spawn(name: "workflow-invoke-async") do
+        invoke(input, config: config)
+      end
+    end
+
     # Resumes a halted workflow. Generic resume that works for all halt types.
     # @param state [Object] halted context
     # @param input [Hash, nil] optional field updates to merge before resuming
@@ -116,6 +139,23 @@ module Phronomy
       @runner.stream(input, config: config, &block)
     end
 
+    private
+
+    # Merges an {InvocationContext} into the config hash.
+    # Existing +config+ keys take precedence (backward-compat).
+    def _apply_invocation_context(config, ic)
+      effective = config.merge(invocation_context: ic)
+      effective = effective.merge(thread_id: ic.thread_id) if effective[:thread_id].nil? && ic.thread_id
+      if effective[:cancellation_token].nil?
+        if (tok = ic.effective_timeout_token)
+          effective = effective.merge(cancellation_token: tok)
+        end
+      end
+      effective
+    end
+
+    public
+
     # ---------------------------------------------------------------------------
     # Internal DSL builder
     # ---------------------------------------------------------------------------
@@ -139,6 +179,8 @@ module Phronomy
         @transitions = []
         # Set of wait state names
         @wait_state_names = []
+        # { state_name => Numeric } — per-state action timeout in seconds
+        @action_timeouts = {}
       end
 
       # Declares the initial (entry) state.
@@ -151,13 +193,17 @@ module Phronomy
       # rubocop:enable Style/TrivialAccessors
 
       # Declares an action state.
-      # @param name   [Symbol]   state name
-      # @param action [#call, nil] optional entry action shorthand.
+      # @param name           [Symbol]        state name
+      # @param action         [#call, nil]    optional entry action shorthand.
       #   +state :generate, action: MY_PROC+ is equivalent to
       #   +state :generate; entry :generate, MY_PROC+.
+      # @param action_timeout [Numeric, nil]  seconds before an async (Task-returning)
+      #   entry action is cancelled and {Phronomy::ActionTimeoutError} is raised.
+      #   Only applies when the action returns a {Task} or {PendingOperation}.
       # @api public
-      def state(name, action: nil)
+      def state(name, action: nil, action_timeout: nil)
         @declared_states << name
+        @action_timeouts[name] = action_timeout if action_timeout
         entry(name, action) if action
       end
 
@@ -309,7 +355,8 @@ module Phronomy
           external_events: external_events,
           entry_point: @initial || @declared_states.first,
           wait_state_names: @wait_state_names,
-          state_store: @state_store
+          state_store: @state_store,
+          action_timeouts: @action_timeouts.dup
         )
 
         Workflow.new(runner)

data/lib/phronomy/workflow_context.rb

@@ -42,7 +42,16 @@ module Phronomy
         end
 
         @fields[name] = {type: type, default: default}
-        attr_accessor name
+
+        # Define getter.
+        attr_reader name
+
+        # Define write-guarded setter.  Mutation from outside the EventLoop
+        # dispatch thread raises WorkflowContextOwnershipError in EventLoop mode.
+        define_method(:"#{name}=") do |value|
+          _assert_write_permitted!
+          instance_variable_set(:"@#{name}", value)
+        end
       end
 
       def fields
@@ -61,6 +70,7 @@ module Phronomy
     #   :<state>           — resuming at <state> (workflow paused before its execution)
     # @return [Symbol]
     # @api public
+    # mutant:disable - @phase is always non-nil (set to :__end__ in initialize, only changed by set_graph_metadata which never sets nil), so the || :__end__ fallback branch is never reached — all mutations of the right-hand side are genuine equivalents
     def phase
       @phase || :__end__
     end
@@ -68,6 +78,7 @@ module Phronomy
     # Returns true if the workflow is paused mid-execution (not yet completed).
     # @return [Boolean]
     # @api public
+    # mutant:disable - phase != :__end__ vs !phase.eql?(:__end__) vs !phase.equal?(:__end__) are genuine equivalents for Symbol (Symbols are interned so == / eql? / equal? all behave identically)
     def halted?
       phase != :__end__
     end
@@ -76,19 +87,23 @@ module Phronomy
     # @param thread_id [String, nil]
     # @param phase [Symbol, nil]
     # @api public
+    # mutant:disable - mutations replacing return value `self` with nil or removing the last line are genuine equivalents: callers chain on the return value only in merge which immediately discards it
     def set_graph_metadata(thread_id: nil, phase: nil)
       @thread_id = thread_id unless thread_id.nil?
       @phase = phase unless phase.nil?
       self
     end
 
+    # mutant:disable - multiple genuine equivalent mutations: is_a?(Proc) vs instance_of?(Proc) (Proc has no subclasses in practice), config[]/fetch() for always-present :default key, @thread_id=nil removal (unset ivar is already nil), @phase=:__end__ → nil or removal (phase method returns :__end__ via @phase||:__end__ fallback), raise message #{.inspect} vs #{} (spec checks exception class not message text)
     def initialize(**attrs)
       unknown = attrs.keys - self.class.fields.keys
       raise ArgumentError, "Unknown WorkflowContext field(s): #{unknown.inspect}" unless unknown.empty?
 
       self.class.fields.each do |name, config|
         default = config[:default].is_a?(Proc) ? config[:default].call : config[:default]
-        send(:"#{name}=", attrs.fetch(name, default))
+        # Bypass the write guard in initialize — ownership enforcement begins
+        # after construction is complete.
+        instance_variable_set(:"@#{name}", attrs.fetch(name, default))
       end
       @thread_id = nil
       @phase = :__end__
@@ -103,6 +118,7 @@ module Phronomy
     # @return [self.class] new context instance
     # @raise [ArgumentError] if updates contains keys that are not declared fields
     # @api public
+    # mutant:disable - multiple genuine equivalent mutations: send/public_send/__send__ are identical (all field accessors are public), fields[]/fetch() and field_config[]/fetch() for always-present keys, updates[]/fetch() when updates.key?(name) is already true, Array() wrapping for append fields that always hold Arrays, (send||{})/send equivalence for merge fields that always hold Hashes, deep_dup_value(send) vs send are equivalent under killfork (coverage selection does not trace the deep_dup_value call site across the fork boundary), raise message inspect vs to_s (spec checks exception class only)
     def merge(updates)
       unknown = updates.keys - self.class.fields.keys
       raise ArgumentError, "Unknown WorkflowContext field(s): #{unknown.inspect}" unless unknown.empty?
@@ -134,6 +150,7 @@ module Phronomy
     # Converts user-defined fields to a Hash (excludes internal workflow metadata).
     # @return [Hash]
     # @api public
+    # mutant:disable - send/public_send/__send__ are genuine equivalents (all field accessors are public methods)
     def to_h
       self.class.fields.keys.each_with_object({}) do |name, h|
         h[name] = send(name)
@@ -142,11 +159,29 @@ module Phronomy
 
     private
 
+    # Asserts that the calling thread is allowed to mutate this context.
+    # No-op when EventLoop mode is disabled.
+    # @raise [Phronomy::WorkflowContextOwnershipError] when called from a
+    #   non-EventLoop thread in EventLoop mode.
+    # @api private
+    # mutant:disable - multiple genuine equivalent mutations: defined?(Phronomy::EventLoop)&& removal is genuine because EventLoop is always loaded in the killfork environment; true&& is genuine (truthy guard); EventLoop.current? resolves to Phronomy::EventLoop.current? within the Phronomy module; WorkflowContextOwnershipError resolves to Phronomy::WorkflowContextOwnershipError within the module; raise without message or with nil message is genuine (spec checks exception class, not message text)
+    def _assert_write_permitted!
+      return unless defined?(Phronomy::EventLoop) &&
+        Phronomy.configuration.event_loop
+      return if Phronomy::EventLoop.current?
+
+      raise Phronomy::WorkflowContextOwnershipError,
+        "WorkflowContext fields may only be mutated from the EventLoop dispatch " \
+        "thread. Use context.merge(...) to produce a new context, or deliver " \
+        "updates as event payloads."
+    end
+
     # Performs a deep copy of a value for immutable context propagation.
     # Arrays and Hashes are deep-duplicated recursively.
     # Immutable values (nil, Symbol, Integer, Float, true/false, frozen String) are returned as-is.
     # Other objects are dup'd (best-effort shallow copy for custom types).
     # Objects that cannot be dup'd (e.g. Proc, Method) are returned as-is.
+    # mutant:disable - multiple genuine equivalent mutations: each class in the when clause (NilClass/Symbol/Integer/Float/TrueClass/FalseClass) can be removed or replaced with nil because all those types are frozen so the else-branch val.frozen? guard returns the same result; return val vs val is also equivalent; if val.frozen? vs if self.frozen? is equivalent since self is never frozen in this context
     def deep_dup_value(val)
       case val
       when Array

data/lib/phronomy/workflow_runner.rb

@@ -45,7 +45,7 @@ module Phronomy
     # Sentinel value for the terminal state of a workflow.
     FINISH = :__end__
 
-    def initialize(state_class:, entry_actions:, declared_states:, auto_transitions:, external_events:, entry_point:, exit_actions: {}, wait_state_names: [], state_store: nil)
+    def initialize(state_class:, entry_actions:, declared_states:, auto_transitions:, external_events:, entry_point:, exit_actions: {}, wait_state_names: [], state_store: nil, action_timeouts: {})
       @state_class = state_class
       @entry_actions = entry_actions   # { state_name => [callable, ...] }
       @declared_states = declared_states
@@ -55,7 +55,17 @@ module Phronomy
       @entry_point = entry_point
       @wait_state_names = wait_state_names
       @state_store = state_store
-      @phase_machine_class = build_phase_machine_class(auto_transitions, exit_actions)
+      @action_timeouts = action_timeouts   # { state_name => seconds }
+      @phase_machine_class = Agent::Lifecycle::PhaseMachineBuilder.new(
+        entry_point: @entry_point,
+        declared_states: @declared_states,
+        wait_state_names: @wait_state_names,
+        external_events: @external_events,
+        entry_actions: @entry_actions,
+        action_timeouts: @action_timeouts,
+        auto_transitions: auto_transitions,
+        exit_actions: exit_actions
+      ).build
     end
 
     # Executes the workflow from the initial state.
@@ -159,7 +169,7 @@ module Phronomy
 
     # Builds an FSMSession for the given context. Used in EventLoop mode.
     def build_session_for(context:, recursion_limit:, resume_event: nil, resume_phase: nil)
-      Phronomy::FSMSession.new(
+      Phronomy::Agent::Lifecycle::FSMSession.new(
         id: context.thread_id,
         context: context,
         entry_point: @entry_point,
@@ -170,6 +180,7 @@ module Phronomy
         external_events: @external_events,
         phase_machine_class: @phase_machine_class,
         recursion_limit: recursion_limit,
+        action_timeouts: @action_timeouts,
         resume_event: resume_event,
         resume_phase: resume_phase
       )
@@ -211,7 +222,20 @@ module Phronomy
         # The entry point has no prior transition, so we invoke its entry actions directly.
         @entry_actions[current_state]&.each do |c|
           result = c.call(ctx)
-          ctx = result if result.is_a?(Phronomy::WorkflowContext)
+          if result.is_a?(Phronomy::Task)
+            timeout_secs = @action_timeouts[current_state]
+            if timeout_secs
+              if result.join(timeout_secs).nil?
+                result.cancel!
+                raise Phronomy::ActionTimeoutError,
+                  "Action in state #{current_state.inspect} timed out after #{timeout_secs}s"
+              end
+            end
+            task_result = result.await
+            ctx = task_result if task_result.is_a?(Phronomy::WorkflowContext)
+          elsif result.is_a?(Phronomy::WorkflowContext)
+            ctx = result
+          end
         end
         tracker.context = ctx
       end
@@ -295,79 +319,6 @@ module Phronomy
     #   before_transition from — exit callbacks (invoked when leaving a state)
     #
     # Guard lambdas bridge the PhaseTracker and WorkflowContext via +m.context+.
-    def build_phase_machine_class(auto_transitions, exit_actions)
-      entry = @entry_point
-      all_states = (@declared_states + @wait_state_names + [:__end__]).uniq
-      auto_trans = auto_transitions  # Array of { from:, to:, guard: }
-      ext_events = @external_events
-      entry_acts = @entry_actions
-      exit_acts = exit_actions
-
-      Class.new do
-        # Holds the current WorkflowContext so guards and callbacks can read it.
-        attr_accessor :context
-
-        state_machine :phase, initial: entry do
-          all_states.each { |s| state s }
-
-          # Auto-fire transitions: all auto transitions unified under :state_completed.
-          # Includes unguarded (unconditional) and guarded (conditional) transitions.
-          # Declaration order is preserved; guards are evaluated before unguarded fallbacks.
-          event :state_completed do
-            auto_trans.each do |t|
-              if t[:guard]
-                guard_proc = t[:guard]
-                transition t[:from] => t[:to], :if => ->(m) { guard_proc.call(m.context) }
-              else
-                transition t[:from] => t[:to]
-              end
-            end
-          end
-
-          # External events: human-in-the-loop triggers from wait states.
-          ext_events.each do |ev_name, transitions|
-            event ev_name do
-              transitions.each do |t|
-                if t[:guard]
-                  guard_proc = t[:guard]
-                  transition t[:from] => t[:to], :if => ->(m) { guard_proc.call(m.context) }
-                else
-                  transition t[:from] => t[:to]
-                end
-              end
-            end
-          end
-
-          # Entry callbacks: fire after_transition into each state.
-          #    Each callable is registered as a separate callback; state_machines
-          #    accumulates them and fires in declaration order.
-          #    If the callable returns a WorkflowContext (e.g. via s.merge(...)),
-          #    the returned context replaces the current one on the tracker.
-          entry_acts.each do |state_name, callables|
-            callables.each do |callable|
-              after_transition to: state_name do |machine|
-                result = callable.call(machine.context)
-                machine.context = result if result.is_a?(Phronomy::WorkflowContext)
-              end
-            end
-          end
-
-          # Exit callbacks: fire before_transition out of each state.
-          #    Each callable is registered as a separate callback; state_machines
-          #    accumulates them and fires in declaration order.
-          exit_acts.each do |state_name, callables|
-            callables.each do |callable|
-              before_transition from: state_name do |machine|
-                callable.call(machine.context)
-              end
-            end
-          end
-        end
-      end
-    rescue => e
-      raise ArgumentError, "Failed to build phase machine: #{e.message}"
-    end
-
     # Creates a PhaseTracker instance initialized to +from_state+.
     def new_phase_machine(from_state)
       machine = @phase_machine_class.new

data/lib/phronomy.rb

@@ -8,10 +8,15 @@ loader = Zeitwerk::Loader.for_gem
 # Teach Zeitwerk that "llm" maps to "LLM" so that file names such as
 # ruby_llm_embeddings.rb resolve to RubyLLMEmbeddings (not RubyLlmEmbeddings).
 loader.inflector.inflect("ruby_llm_embeddings" => "RubyLLMEmbeddings")
+loader.inflector.inflect("rag_knowledge" => "RAGKnowledge")
 # FSMSession: Zeitwerk would infer "FsmSession" — override to "FSMSession".
 loader.inflector.inflect("fsm_session" => "FSMSession")
 # AgentFSM: Zeitwerk would infer "Fsm" — override to "FSM".
 loader.inflector.inflect("fsm" => "FSM")
+# LLMAdapter: Zeitwerk would infer "LlmAdapter" — override to "LLMAdapter".
+loader.inflector.inflect("llm_adapter" => "LLMAdapter")
+# LLMAdapter::RubyLLM: "ruby_llm" maps to "RubyLLM" (not "RubyLlm").
+loader.inflector.inflect("ruby_llm" => "RubyLLM")
 loader.setup
 
 require_relative "phronomy/version"
@@ -50,6 +55,22 @@ module Phronomy
   # Separate from TimeoutError (deadline exceeded) — this is an intentional stop.
   class CancellationError < Error; end
 
+  # Raised when {Agent#invoke} (a synchronous, blocking call) is attempted from
+  # inside an active scheduler task and +strict_runtime_guards+ is enabled.
+  #
+  # Calling a blocking invocation from within a scheduler task stalls the
+  # scheduler until the inner invocation completes, preventing other tasks from
+  # making progress (hidden deadlock risk).  Use {Agent#invoke_async} followed by
+  # +#await+ inside scheduler tasks instead.
+  #
+  # This error is only raised when:
+  #   Phronomy.configure { |c| c.strict_runtime_guards = true }
+  #
+  # By default a warning is logged and execution continues.
+  #
+  # @see Phronomy::Runtime.in_scheduler_context?
+  class SchedulerReentrancyError < Error; end
+
   # Raised by {Phronomy::GeneratorVerifier#invoke} when +raise_if_untrusted: true+
   # and the pipeline's combined confidence score falls below the configured threshold.
   #
@@ -76,6 +97,28 @@ module Phronomy
     end
   end
 
+  # Raised when an operation is submitted to a {BlockingAdapterPool} that has
+  # already been shut down via {BlockingAdapterPool#shutdown}.
+  class PoolShutdownError < Error; end
+
+  # Raised when a concurrency limit is exceeded and the configured backpressure
+  # strategy is +:raise+. The caller should back off and retry.
+  class BackpressureError < Error; end
+
+  # Raised by {CancellationScope#pop_queue} when the deadline expires before a
+  # result is available. Extends {TimeoutError} for backwards compatibility.
+  class ScopeTimeoutError < TimeoutError; end
+
+  # Raised when a Workflow entry/exit action task exceeds the +action_timeout:+
+  # configured for its state.  Extends {TimeoutError}.
+  class ActionTimeoutError < TimeoutError; end
+
+  # Raised when a {Phronomy::WorkflowContext} field is mutated from a thread
+  # that does not own the context (i.e. not the EventLoop dispatch thread).
+  # Only raised in EventLoop mode.  Use +context.merge(...)+ to produce a new
+  # context, or deliver updates as +:child_completed+ event payloads.
+  class WorkflowContextOwnershipError < Error; end
+
   class << self
     def configuration
       @configuration ||= Configuration.new