phronomy 0.11.0 → 0.12.0

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

@@ -192,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
@@ -252,9 +252,9 @@ module Phronomy
         effective_name = prepared.new.name
         Class.new(prepared) do
           tool_name effective_name
-          define_method(:call) do |args|
+          define_method(:call) do |args, **kwargs|
             self._orchestrator_context = orch.instance_variable_get(:@_orchestrator_context)
-            super(args)
+            super(args, **kwargs)
           end
         end
       end
@@ -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/tools/mcp.rb

@@ -35,39 +35,43 @@ module Phronomy
         #   - "stdio://<command>"  — spawn a child process
         #   - "http://<url>" / "https://<url>" — connect to an HTTP/SSE server
         # @param tool_name [String] the tool name as registered in the MCP server
+        # @param headers [Hash] additional HTTP request headers forwarded to every
+        #   request (tool discovery and tool execution). Ignored for stdio transports.
+        #   Typical use: <tt>headers: { "Authorization" => "Bearer #{ENV['API_KEY']}" }</tt>
         # @return [Mcp] a configured subclass instance ready for use with an Agent
         # @api public
-        def from_server(server_uri, tool_name:)
+        def from_server(server_uri, tool_name:, headers: {})
           # Use a short-lived transport only to query the tool definition,
           # then close it.  Each Mcp instance creates its own transport
           # so that concurrent callers never share IO streams.
-          transport = build_transport(server_uri)
+          transport = build_transport(server_uri, headers: headers)
           begin
             tool_def = transport.fetch_tool(tool_name)
           ensure
             transport.close
           end
-          build_tool_class(tool_name, server_uri, tool_def).new
+          build_tool_class(tool_name, server_uri, tool_def, headers: headers).new
         end
 
         private
 
-        def build_transport(uri)
+        def build_transport(uri, headers: {})
           scheme, path = uri.split("://", 2)
           case scheme
           when "stdio"
             StdioTransport.new(path)
           when "http", "https"
-            HttpTransport.new(uri)
+            HttpTransport.new(uri, headers: headers)
           else
             raise ArgumentError, "Unsupported MCP transport scheme: #{scheme.inspect}. Supported: 'stdio://', 'http://', 'https://'."
           end
         end
 
-        def build_tool_class(tool_name, server_uri, tool_def)
+        def build_tool_class(tool_name, server_uri, tool_def, headers: {})
           klass = Class.new(Mcp)
           klass.tool_name(tool_name)
           klass.instance_variable_set(:@mcp_server_uri, server_uri)
+          klass.instance_variable_set(:@mcp_headers, headers)
 
           # Register description and params from the MCP tool definition.
           klass.description(tool_def[:description] || tool_name)
@@ -82,7 +86,8 @@ module Phronomy
           # never share IO streams, eliminating the need for synchronisation.
           klass.define_method(:initialize) do
             uri = self.class.instance_variable_get(:@mcp_server_uri)
-            @mcp_transport = self.class.send(:build_transport, uri)
+            hdrs = self.class.instance_variable_get(:@mcp_headers) || {}
+            @mcp_transport = self.class.send(:build_transport, uri, headers: hdrs)
           end
 
           klass.define_method(:execute) do |**args|
@@ -158,7 +163,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
@@ -249,8 +254,10 @@ module Phronomy
               raise Phronomy::ToolError,
                 "MCP stdio server did not start within #{@startup_timeout} seconds"
             end
-            line = @stdout.gets
-            @stdout.ungetbyte(line) if line
+            # Do NOT call @stdout.gets here: gets() blocks until a newline arrives,
+            # which hangs indefinitely when the server emits no startup line or a
+            # partial line without '\n'.  IO.select already confirmed the server is
+            # alive and responsive; the first rpc_call will consume actual output.
           end
         end
 

data/lib/phronomy/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Phronomy
-  VERSION = "0.11.0"
+  VERSION = "0.12.0"
 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,