phronomy 0.10.0 → 0.11.1

data/lib/phronomy/engine/task/deferred_backend.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require "timeout"
+
+module Phronomy
+  class Task
+    # Backend for externally-completed Tasks.
+    #
+    # DeferredBackend never starts a thread.  The owner transitions it to a
+    # terminal state by calling Task#transition! and then #unblock.
+    # @api private
+    class DeferredBackend < Backend
+      def initialize(task:, &)
+        super
+        @done_queue = Queue.new
+        task.transition!(:running)
+      end
+
+      # Unblocks await/join after the task reaches a terminal state.
+      # @api private
+      def unblock(value, error)
+        @done_queue.push([value, error])
+      end
+
+      # Blocks until externally completed.
+      # @api private
+      def wait_result
+        scheduler = Thread.current.thread_variable_get(Task::SCHEDULER_KEY)
+        in_managed_fiber = !Fiber.respond_to?(:main) || Fiber.current != Fiber.main
+        if scheduler && in_managed_fiber && !@task.done?
+          scheduler.track_blocking_await
+          waiting_fiber = Fiber.current
+          @task.on_complete do |_value, _error|
+            scheduler.complete_blocking_await
+            scheduler.enqueue_fiber(-> { waiting_fiber.resume })
+          end
+          Fiber.yield(:cooperative_suspend)
+        end
+
+        value, error = @done_queue.pop
+        raise error if error
+
+        value
+      end
+
+      # Deferred tasks have no execution thread of their own.
+      # @api private
+      def alive?
+        !@task.done?
+      end
+
+      # Marks the task cancelled without interrupting external work.
+      # @api private
+      def cancel!
+        self
+      end
+
+      # Blocks until externally completed, with optional timeout.
+      # @api private
+      def join(limit = nil)
+        if limit.nil?
+          wait_result
+        else
+          begin
+            Timeout.timeout(limit) { wait_result }
+          rescue Timeout::Error
+            nil
+          end
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/{task → engine/task}/fiber_backend.rb

@@ -100,7 +100,7 @@ module Phronomy
       # @return [Object]
       # @raise [Exception]
       # @api private
-      def await
+      def wait_result
         unless @fiber.alive?
           raise @error if @error
           return @value

data/lib/phronomy/{task → engine/task}/immediate_backend.rb

@@ -44,7 +44,7 @@ module Phronomy
       # @return [Object]
       # @raise [Exception]
       # @api private
-      def await
+      def wait_result
         raise @error if @error
 
         @value

data/lib/phronomy/{task → engine/task}/mapped_backend.rb

@@ -37,7 +37,19 @@ module Phronomy
       # @return [Object] the mapped value
       # @raise [Exception] if the source task or the map block raised an error
       # @api private
-      def await
+      def wait_result
+        scheduler = Thread.current.thread_variable_get(Task::SCHEDULER_KEY)
+        in_managed_fiber = !Fiber.respond_to?(:main) || Fiber.current != Fiber.main
+        if scheduler && in_managed_fiber && !@task.done?
+          scheduler.track_blocking_await
+          waiting_fiber = Fiber.current
+          @task.on_complete do |_value, _error|
+            scheduler.complete_blocking_await
+            scheduler.enqueue_fiber(-> { waiting_fiber.resume })
+          end
+          Fiber.yield(:cooperative_suspend)
+        end
+
         value, error = @done_queue.pop
         raise error if error
 
@@ -64,10 +76,10 @@ module Phronomy
       # @api private
       def join(limit = nil)
         if limit.nil?
-          await
+          wait_result
         else
           begin
-            Timeout.timeout(limit) { await }
+            Timeout.timeout(limit) { wait_result }
           rescue Timeout::Error
             nil
           end

data/lib/phronomy/{task → engine/task}/thread_backend.rb

@@ -41,7 +41,7 @@ module Phronomy
       # @return [Object]
       # @raise [Exception]
       # @api private
-      def await
+      def wait_result
         @thread.join
         raise @error if @error
 

data/lib/phronomy/{task.rb → engine/task.rb}

@@ -5,6 +5,7 @@ require_relative "task/thread_backend"
 require_relative "task/immediate_backend"
 require_relative "task/fiber_backend"
 require_relative "task/mapped_backend"
+require_relative "task/deferred_backend"
 
 module Phronomy
   # A single unit of concurrent work.
@@ -21,7 +22,7 @@ module Phronomy
   #
   # @example Basic usage (framework/test code only — prefer Runtime.instance.spawn in app code)
   #   task = Phronomy::Task.spawn { expensive_io() }
-  #   result = task.await   # blocks until done, re-raises errors
+  #   result = task.wait_result   # blocks until done, re-raises errors
   #
   # @example Cancel a running task
   #   task = Phronomy::Task.spawn { loop { Phronomy::Task.checkpoint! } }
@@ -121,6 +122,15 @@ module Phronomy
       new(name: name, parent: parent, backend_class: backend_class, &block)
     end
 
+    # Creates a task whose lifecycle is completed externally.
+    # @param name [String, nil]
+    # @param parent [Task, nil]
+    # @return [Task]
+    # @api private
+    def self.deferred(name: nil, parent: current)
+      new(name: name, parent: parent, backend_class: DeferredBackend) {}
+    end
+
     # @return [String, nil] optional human-readable label
     attr_reader :name
 
@@ -161,8 +171,8 @@ module Phronomy
     # @return [Object] the result produced by the block
     # @raise [Exception] if the block raised an error
     # @api private
-    def await
-      @backend.await
+    def wait_result
+      @backend.wait_result
     end
 
     # Registers a callback to be invoked when the task reaches a terminal state
@@ -170,7 +180,7 @@ module Phronomy
     #
     # The callback receives two arguments: +value+ (the task's return value,
     # or +nil+) and +error+ (the exception, or +nil+).  These are provided
-    # directly so the callback does not need to call +task.await+, which would
+    # directly so the callback does not need to call +task.wait_result+, which would
     # risk a self-join error when the callback runs inside the task's own thread.
     #
     # If the task is already done when this method is called, the callback is
@@ -204,7 +214,7 @@ module Phronomy
     #
     # The primary use-case is transforming an agent result into a
     # {WorkflowContext} so that a Workflow entry action can return a Task
-    # whose value is picked up by {Workflow::FSMSession} via the existing
+    # whose value is picked up by {FSMSession} via the existing
     # +:action_completed+ path:
     #
     # @example Returning agent output into a Workflow state field
@@ -237,13 +247,15 @@ module Phronomy
             mapped_error = e
           end
         end
+        # Unblock mapped.wait_result / mapped.join before the terminal transition.
+        # on_complete callbacks may resume a waiting Fiber immediately; the
+        # queue must already contain the result at that point.
+        mapped.backend.unblock(mapped_value, mapped_error)
         if mapped_error
           mapped.transition!(:failed, error: mapped_error)
         else
           mapped.transition!(:completed, value: mapped_value)
         end
-        # Unblock mapped.await / mapped.join after the terminal transition.
-        mapped.backend.unblock(mapped_value, mapped_error)
       end
       mapped
     end

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

@@ -58,7 +58,7 @@ module Phronomy
         #     still returns 0.0 — warn is a side-effect not tested by value assertions
         def score(actual:, expected:, input: nil)
           prompt = format(@prompt_template, input: input.to_s, expected: expected.to_s, actual: actual.to_s)
-          response = Phronomy::Runtime.instance.blocking_io.submit { RubyLLM.chat(model: @model).ask(prompt) }.await
+          response = Phronomy::Runtime.instance.blocking_io.submit { RubyLLM.chat(model: @model).ask(prompt) }.blocking_wait
           response.content.to_s.strip.scan(/-?\d+\.?\d*/).first.to_f.clamp(0.0, 1.0)
         rescue => e
           raise if @raise_on_error

data/lib/phronomy/filter/base.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Filter
+    # Abstract base class for value filters.
+    #
+    # A filter may either transform a value (return the new value) or block it
+    # (raise {Phronomy::FilterBlockError}).  The same filter instance can be
+    # registered at multiple call sites — input, output, and tool result.
+    #
+    # @example PII masking filter
+    #   class PiiMaskFilter < Phronomy::Filter::Base
+    #     def call(value, **_context)
+    #       value.to_s
+    #            .gsub(/\b\d{2,4}-\d{2,4}-\d{4}\b/, "[PHONE]")
+    #            .gsub(/\b(?:\d{4}[- ]?){3}\d{4}\b/, "[CARD]")
+    #     end
+    #   end
+    #
+    # @example Blocking filter
+    #   class NoBadWordFilter < Phronomy::Filter::Base
+    #     def call(value, **_context)
+    #       block!("Forbidden content detected") if value.to_s.include?("badword")
+    #       value
+    #     end
+    #   end
+    #
+    # @api public
+    class Base
+      # Process +value+ and return the (possibly transformed) result.
+      #
+      # The +context+ keyword arguments vary by call site:
+      #   - Tool result: +{ tool_name: String, args: Hash }+
+      #   - Input / output: +(empty)+
+      #
+      # @param value   [Object] the value being filtered
+      # @param context [Hash]   optional call-site metadata
+      # @return [Object] the transformed value (or the original if unchanged)
+      # @raise [Phronomy::FilterBlockError] to reject the value
+      # @api public
+      def call(value, **_context)
+        raise NotImplementedError, "#{self.class}#call is not implemented"
+      end
+
+      protected
+
+      # Reject the value with a human-readable reason.
+      # @param reason [String]
+      # @raise [Phronomy::FilterBlockError]
+      # @api public
+      def block!(reason)
+        raise Phronomy::FilterBlockError.new(reason, filter: self)
+      end
+    end
+  end
+end

data/lib/phronomy/{guardrail/prompt_injection_guardrail.rb → filter/prompt_injection_filter.rb}

@@ -1,28 +1,31 @@
 # frozen_string_literal: true
 
 module Phronomy
-  module Guardrail
+  module Filter
     # Detects potential prompt injection attempts in the agent input.
     #
     # Prompt injection is an attack where an adversary embeds LLM instructions
     # inside data sources (e.g. RAG chunks, tool results, user input) to override
     # the agent's intended behaviour.
     #
-    # This guardrail scans the input string for common injection patterns and
-    # calls {#fail!} when a match is found.  It is intended to be registered as
-    # an input guardrail on agents that consume untrusted external content.
+    # This filter scans the input string for common injection patterns and
+    # calls {#block!} when a match is found.  It is intended to be registered as
+    # an input filter on agents that consume untrusted external content.
     #
     # @example
     #   class MyAgent < Phronomy::Agent::Base
     #     model "gpt-4o"
-    #     input_guardrails Phronomy::Guardrail::PromptInjectionGuardrail.new
+    #     input_filter Phronomy::Filter::PromptInjectionFilter
     #   end
     #
     # @example Custom patterns
-    #   guard = Phronomy::Guardrail::PromptInjectionGuardrail.new(
+    #   filter = Phronomy::Filter::PromptInjectionFilter.new(
     #     extra_patterns: [/exfiltrate/i]
     #   )
-    class PromptInjectionGuardrail < InputGuardrail
+    #   agent.add_input_filter(filter)
+    #
+    # @api public
+    class PromptInjectionFilter < Base
       # Common prompt injection / jailbreak patterns.
       DEFAULT_PATTERNS = [
         /ignore\s+(previous|prior|all)\s+instructions?/i,
@@ -38,20 +41,24 @@ module Phronomy
       ].freeze
 
       # @param extra_patterns [Array<Regexp>] additional patterns to scan for
-      # @api private
+      # @api public
       def initialize(extra_patterns: [])
         super()
         @patterns = DEFAULT_PATTERNS + extra_patterns
       end
 
       # Scans the input string for injection patterns.
-      # @param input [String, Hash]
-      # @api private
-      def check(input)
-        text = input.is_a?(Hash) ? input.values.join(" ") : input.to_s
+      # @param value [String, Hash]
+      # @param context [Hash]
+      # @return [String, Hash] the original value when no injection is detected
+      # @raise [Phronomy::FilterBlockError] when a pattern matches
+      # @api public
+      def call(value, **_context)
+        text = value.is_a?(Hash) ? value.values.join(" ") : value.to_s
         @patterns.each do |pattern|
-          fail!("Potential prompt injection detected") if text.match?(pattern)
+          block!("Potential prompt injection detected") if text.match?(pattern)
         end
+        value
       end
     end
   end

data/lib/phronomy/filter.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+# Convenience require for Filter sub-classes.
+require_relative "filter/base"
+require_relative "filter/prompt_injection_filter"

data/lib/phronomy/generator_verifier.rb

@@ -66,8 +66,7 @@ module Phronomy
     # @!attribute [r] trusted
     #   @return [Boolean] true when confidence >= threshold
     Result = Struct.new(
-      :output, :confidence, :citations, :iterations, :review_notes, :trusted,
-      keyword_init: true
+      :output, :confidence, :citations, :iterations, :review_notes, :trusted
     ) do
       # @return [Boolean] true when confidence >= threshold
       alias_method :trusted?, :trusted
@@ -193,21 +192,30 @@ module Phronomy
         entry :draft, ->(state) {
           feedback = state.review_notes.last
           prompt = dpb.call(state.input, feedback)
-          result = draft_agent.invoke(prompt)
-          parsed = drp.call(result[:output])
-          state.draft = parsed[:answer].to_s
-          state.self_score = pipeline.__send__(:clamp, parsed[:confidence])
-          state.citations = pipeline.__send__(:normalize_citations, parsed[:citations])
-          state.iteration = state.iteration + 1
+          # Return a Task so WorkflowRunner awaits it off the EventLoop thread,
+          # then posts :action_completed with the new context back to EventLoop.
+          draft_agent.invoke_async(prompt).map do |result|
+            parsed = drp.call(result[:output])
+            state.merge(
+              draft: parsed[:answer].to_s,
+              self_score: pipeline.__send__(:clamp, parsed[:confidence]),
+              citations: pipeline.__send__(:normalize_citations, parsed[:citations]),
+              iteration: state.iteration + 1
+            )
+          end
         }
 
         entry :review, ->(state) {
           prompt = rpb.call(state.input, state.draft, state.citations)
-          result = review_agent.invoke(prompt)
-          parsed = rrp.call(result[:output])
-          state.review_score = pipeline.__send__(:clamp, parsed[:score])
-          state.approved = parsed[:approved] == true
-          state.review_notes << parsed[:feedback].to_s
+          # Return a Task so WorkflowRunner awaits it off the EventLoop thread.
+          review_agent.invoke_async(prompt).map do |result|
+            parsed = rrp.call(result[:output])
+            state.merge(
+              review_score: pipeline.__send__(:clamp, parsed[:score]),
+              approved: parsed[:approved] == true,
+              review_notes: [parsed[:feedback].to_s]
+            )
+          end
         }
 
         entry :finalize, ->(state) { state.output = state.draft }

data/lib/phronomy/multi_agent/orchestrator.rb

@@ -84,7 +84,7 @@ module Phronomy
               input,
               thread_id: ctx[:thread_id] || parent_ic&.thread_id,
               config: task_config
-            ).await
+            ).wait_result
             result[:output]
           rescue
             raise if on_error == :raise
@@ -217,7 +217,7 @@ module Phronomy
           input,
           config: effective_config,
           thread_id: thread_id || ctx[:thread_id] || parent_ic&.thread_id
-        ).await
+        ).wait_result
       end
 
       private
@@ -306,7 +306,7 @@ module Phronomy
               task[:input],
               config: task_config,
               thread_id: task[:thread_id] || invocation_context&.thread_id
-            ).await
+            ).wait_result
           rescue => e
             errors[i] = e unless on_error == :skip
           end
@@ -324,7 +324,7 @@ module Phronomy
               "(#{alive.length} of #{spawned.length} tasks still running)"
           end
         else
-          spawned.each(&:await)
+          spawned.each(&:wait_result)
         end
 
         first_error = errors.compact.first

data/lib/phronomy/multi_agent/parallel_tool_chat.rb

@@ -77,7 +77,7 @@ module Phronomy
         # Thread that previously wrapped each pool operation.
         #
         # Both Phronomy::Task and BlockingAdapterPool::PendingOperation support
-        # #await, so results are collected uniformly below.
+        # #wait_result, so results are collected uniformly below.
         ct = @cancellation_token
         max = @max_parallel_tools
         tool_results = tool_calls.each_slice(max).flat_map do |batch|
@@ -105,7 +105,7 @@ module Phronomy
 
           # Await all dispatched operations in original order.
           dispatched.map do |item|
-            result = item[:awaitable] ? item[:awaitable].await : item[:result]
+            result = item[:awaitable] ? item[:awaitable].wait_result : item[:result]
             {tool_call: item[:tool_call], result: result}
           end
         end
@@ -142,7 +142,7 @@ module Phronomy
           tool: tool,
           args: tool_call.arguments,
           cancellation_token: @cancellation_token
-        ).await
+        ).wait_result
       end
     end
   end

data/lib/phronomy/multi_agent/team_coordinator.rb

@@ -47,8 +47,7 @@ module Phronomy
         :index,    # Integer — 0-based worker index
         :agent,    # Agent::Base instance
         :messages, # Array  — accumulated conversation history
-        :status,   # Symbol — :idle | :available | :done
-        keyword_init: true
+        :status    # Symbol — :idle | :available | :done
       ) do
         # Returns true when this worker is ready to accept the next task.
         def available? = [:idle, :available].include?(status)

data/lib/phronomy/tools/mcp.rb

@@ -158,7 +158,7 @@ module Phronomy
           @wait_thr = nil
           stderr_thread&.join(1)
           begin
-            stderr_op&.await(timeout: 1.0)
+            stderr_op&.blocking_wait(timeout: 1.0)
           rescue
             nil
           end

data/lib/phronomy/version.rb

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

data/lib/phronomy/workflow/phase_machine_builder.rb

@@ -170,11 +170,7 @@ module Phronomy
       # @api private
       def handle_entry_action_result(machine, result, state_name, timeout_secs)
         if result.is_a?(Phronomy::Task)
-          if Phronomy.configuration.event_loop
-            dispatch_task_in_event_loop(machine, result, state_name, timeout_secs)
-          else
-            await_task_blocking(machine, result, state_name, timeout_secs)
-          end
+          dispatch_task_in_event_loop(machine, result, state_name, timeout_secs)
         elsif result.is_a?(Phronomy::WorkflowContext)
           machine.context = result
         end
@@ -195,19 +191,34 @@ module Phronomy
       def dispatch_task_in_event_loop(machine, result, state_name, timeout_secs)
         machine.async_pending = true
         thread_id = machine.context.thread_id
-        Phronomy::Runtime.instance.spawn(name: "wf-await-#{thread_id}") do
-          enforce_timeout!(result, state_name, timeout_secs)
-          task_result = result.await
+        if timeout_secs
+          Phronomy::Runtime.instance.timer_queue.schedule(seconds: timeout_secs) do
+            next if result.done?
+
+            Phronomy::EventLoop.instance.post(
+              Phronomy::Event.new(
+                type: :error,
+                target_id: Phronomy::EventLoop::SYSTEM_CHANNEL_ID,
+                payload: {session_id: thread_id, result: Phronomy::ActionTimeoutError.new(
+                  "Action in state #{state_name.inspect} timed out after #{timeout_secs}s"
+                )}
+              )
+            )
+          end
+        end
+        result.on_complete do |task_result, error|
+          if error
+            Phronomy::EventLoop.instance.post(
+              Phronomy::Event.new(type: :error, target_id: Phronomy::EventLoop::SYSTEM_CHANNEL_ID, payload: {session_id: thread_id, result: error})
+            )
+            next
+          end
           ev = if task_result.is_a?(Phronomy::WorkflowContext)
             Phronomy::Event.new(type: :action_completed, target_id: thread_id, payload: task_result)
           else
             Phronomy::Event.new(type: :state_completed, target_id: thread_id, payload: nil)
           end
           Phronomy::EventLoop.instance.post(ev)
-        rescue => e
-          Phronomy::EventLoop.instance.post(
-            Phronomy::Event.new(type: :error, target_id: thread_id, payload: e)
-          )
         end
       end
 
@@ -223,7 +234,7 @@ module Phronomy
       # @api private
       def await_task_blocking(machine, result, state_name, timeout_secs)
         enforce_timeout!(result, state_name, timeout_secs)
-        task_result = result.await
+        task_result = result.wait_result
         machine.context = task_result if task_result.is_a?(Phronomy::WorkflowContext)
       end
 

data/lib/phronomy/workflow.rb

@@ -96,6 +96,11 @@ module Phronomy
 
     # Invokes this workflow asynchronously and returns a {Phronomy::Task}.
     #
+    # Unlike {#invoke}, this method registers the workflow session with the
+    # EventLoop and returns immediately without spawning an extra OS thread.
+    # The returned Task resolves with the final context when the workflow
+    # finishes.
+    #
     # @param input  [Hash]
     # @param config [Hash]
     # @param invocation_context [Phronomy::InvocationContext, nil]
@@ -105,9 +110,7 @@ module Phronomy
       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
+      @runner.invoke_deferred(input, config: config)
     end
 
     # Resumes a halted workflow. Generic resume that works for all halt types.

data/lib/phronomy/workflow_context.rb

@@ -160,14 +160,16 @@ 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.
+    # Raises WorkflowContextOwnershipError when called from outside the EventLoop
+    # dispatch thread, unless we are inside a synchronous execution context
+    # (e.g. Workflow#stream using the run_workflow sync path).
+    # @raise [Phronomy::WorkflowContextOwnershipError]
     # @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 unless defined?(Phronomy::EventLoop)
+      # Allow mutations when executing synchronously (e.g. Workflow#stream via run_workflow).
+      return if Thread.current[:phronomy_sync_execution]
       return if Phronomy::EventLoop.current?
 
       raise Phronomy::WorkflowContextOwnershipError,