phronomy 0.17.0 → 0.18.0

data/examples/workflows/generic_task_event_mapping.rb

@@ -19,18 +19,25 @@ class ImportContext
   end
 end
 
+# Example application service for synchronous work that must stay off EventLoop.
+# The worker Thread belongs to Phronomy's bounded OffloadPool; the Workflow
+# itself never blocks EventLoop waiting for the operation.
+def start_import_async
+  Phronomy::Runtime.instance.offload.submit(on_full: :raise) do
+    # Replace with blocking file/DB/network work or another long synchronous call.
+    100
+  end
+end
+
 workflow = nil
 
 workflow = Phronomy::Workflow.define(ImportContext) do
   initial :importing
 
   state :importing, action: ->(context) {
-    task = Phronomy::Runtime.instance.spawn do
-      # Replace with application-owned asynchronous work.
-      100
-    end
+    operation = start_import_async
 
-    task.on_complete do |record_count, error|
+    operation.on_complete do |record_count, error|
       workflow.signal(
         thread_id: context.thread_id,
         event: error ? :import_failed : :import_completed,
@@ -41,7 +48,8 @@ workflow = Phronomy::Workflow.define(ImportContext) do
       )
     end
 
-    # Do not return task. The state is active after this synchronous entry ends.
+    # Do not return the completion handle. The state remains active after this
+    # synchronous action returns, and later completion arrives as an FSM event.
     context
   }
 

data/lib/phronomy/agent/agent_invocation_session_builder.rb

@@ -4,7 +4,7 @@ module Phronomy
   module Agent
     # Builds FSMSession instances for AgentInvocation objects.
     #
-    # Blocking/provider work returns through explicit Agent-internal events.
+    # Offloaded/provider work returns through explicit Agent-internal events.
     # Entry actions start operations and return synchronously.
     # Every LLM Call is prepared from a canonical Manifest and RuntimeProjection.
     #
@@ -272,7 +272,7 @@ module Phronomy
       def self.prepare_and_start_llm_call(agent, runtime, invocation, streaming:)
         activation = invocation.config.fetch(:phronomy_activation)
         if invocation.user_message_sent
-          preparation = runtime.blocking_io.submit do
+          preparation = runtime.offload.submit(on_full: :raise) do
             activation.coordinator.prepare_next_llm_call(activation)
           end
           preparation.on_complete do |projection, error|

data/lib/phronomy/agent/async_event_api.rb

@@ -9,7 +9,7 @@ module Phronomy
         if invocation_context
           thread_id, config = _apply_invocation_context(thread_id, config, invocation_context)
         end
-        _check_scheduler_reentrancy(:invoke, :invoke_async)
+        _check_event_loop_reentrancy(:invoke, :invoke_async)
         trace("agent.invoke", input: input, **_build_caller_meta(config)) do |_span|
           result = invoke_async(
             input,
@@ -58,7 +58,7 @@ module Phronomy
         if invocation_context
           thread_id, config = _apply_invocation_context(thread_id, config, invocation_context)
         end
-        _check_scheduler_reentrancy(:stream, :stream_async)
+        _check_event_loop_reentrancy(:stream, :stream_async)
         trace("agent.stream", input: input, **_build_caller_meta(config)) do |_span|
           result = stream_async(
             input,
@@ -98,7 +98,7 @@ module Phronomy
       end
 
       def approve(execution_id, approval_request_id:, approved: true, config: {})
-        _check_scheduler_reentrancy(:approve, :approve_async)
+        _check_event_loop_reentrancy(:approve, :approve_async)
         approve_async(
           execution_id,
           approval_request_id: approval_request_id,

data/lib/phronomy/agent/base.rb

@@ -553,35 +553,20 @@ module Phronomy
         [effective_thread_id, effective_config]
       end
 
-      def _check_scheduler_reentrancy(sync_method, async_method)
+      def _check_event_loop_reentrancy(sync_method, async_method)
         if Phronomy::Runtime.instance.event_loop.current?
-          raise Phronomy::SchedulerReentrancyError,
+          raise Phronomy::EventLoopReentrancyError,
             "#{self.class.name}##{sync_method} cannot run on the EventLoop thread. " \
             "Use #{async_method} and return immediately."
         end
-
-        return unless Phronomy::Task.current
-
-        msg = "#{self.class.name}##{sync_method} called from inside a scheduler task. " \
-          "This blocks the scheduler until the inner invocation completes, preventing " \
-          "other tasks from making progress. Use #{async_method} + await instead."
-        if Phronomy.configuration.strict_runtime_guards
-          raise Phronomy::SchedulerReentrancyError, msg
-        elsif Phronomy.configuration.logger
-          Phronomy.configuration.logger.warn(msg)
-        else
-          Kernel.warn("[phronomy] WARNING: #{msg}")
-        end
       end
 
       def _complete_result_task(task, result)
-        task.backend.unblock(result, nil)
-        task.transition!(:completed, value: result)
+        task.complete(result)
       end
 
       def _fail_result_task(task, error)
-        task.backend.unblock(nil, error)
-        task.transition!(:failed, error: error)
+        task.fail(error)
       end
 
       def _translated_error(error)
@@ -782,6 +767,10 @@ module Phronomy
         return resolved if result_filters.empty?
 
         effective_name = resolved.new.name
+        custom_async_call =
+          resolved.instance_method(:call_async).owner !=
+          Phronomy::Agent::Context::Capability::Base
+
         Class.new(resolved) do
           tool_name effective_name
           define_method(:call) do |args, **kwargs|
@@ -790,6 +779,33 @@ module Phronomy
               filter.call(val, tool_name: name, args: args)
             }
           end
+
+          # Base#call_async ultimately executes #call, so the synchronous wrapper
+          # above already applies filters for ordinary Tools. Agent-backed Tools
+          # override #call_async and bypass #call; only those custom async Tools
+          # need an asynchronous result-filter wrapper here.
+          if custom_async_call
+            define_method(:call_async) do |args, **kwargs|
+              source = super(args, **kwargs)
+              filtered = Phronomy::Task.deferred(name: "tool-filter-#{name}")
+              source.on_complete do |value, error|
+                if error
+                  filtered.fail(error)
+                  next
+                end
+
+                begin
+                  result = result_filters.inject(value) { |val, filter|
+                    filter.call(val, tool_name: name, args: args)
+                  }
+                  filtered.complete(result)
+                rescue => filter_error
+                  filtered.fail(filter_error)
+                end
+              end
+              filtered
+            end
+          end
         end
       end
     end

data/lib/phronomy/agent/context/capability/base.rb

@@ -113,16 +113,22 @@ module Phronomy
 
             public
 
+            # Declares whether Tool work is safe to run cooperatively on the EventLoop
+            # or must be offloaded to a bounded worker pool.
+            #
+            # Phronomy does not classify the reason for offloading. Blocking I/O,
+            # CPU-bound synchronous work, and other long synchronous calls all use
+            # +:offloaded+. The application owns that workload classification.
             # @api public
             def execution_mode(value = nil)
               if value.nil?
                 return @execution_mode if instance_variable_defined?(:@execution_mode)
                 return superclass.execution_mode if superclass.respond_to?(:execution_mode)
 
-                return :blocking_io
+                return :offloaded
               end
 
-              valid = %i[cooperative blocking_io cpu_bound external_process]
+              valid = %i[cooperative offloaded]
               unless valid.include?(value)
                 raise ArgumentError,
                   "execution_mode must be one of #{valid.inspect}, got #{value.inspect}"
@@ -296,7 +302,11 @@ module Phronomy
           end
 
           # @api public
-          def call_async(args, cancellation_token: nil, config: {})
+          def call_async(
+            args,
+            cancellation_token: nil,
+            config: {}
+          )
             Phronomy::Agent::ToolExecutor.call_async(
               tool: self,
               args: args,

data/lib/phronomy/agent/execution_coordinator.rb

@@ -19,7 +19,7 @@ module Phronomy
       )
         result_task = Phronomy::Task.deferred(name: "agent-#{@agent.agent_id}-#{mode}")
         runtime = Phronomy::Runtime.instance
-        preparation = runtime.blocking_io.submit do
+        preparation = runtime.offload.submit(on_full: :raise) do
           prepare(input, thread_id: thread_id, config: config)
         end
         preparation.on_complete do |prepared, error|
@@ -52,7 +52,7 @@ module Phronomy
           name: "agent-approval-resume:#{execution_id}"
         )
         runtime = Phronomy::Runtime.instance
-        preparation = runtime.blocking_io.submit do
+        preparation = runtime.offload.submit(on_full: :raise) do
           execution = @agent.persistence.executions.load(execution_id)
           unless execution.agent_id == @agent.agent_id && execution.status == :suspended
             raise ArgumentError,
@@ -86,7 +86,7 @@ module Phronomy
               config: config
             )
           rescue => start_error
-            commit = runtime.blocking_io.submit do
+            commit = runtime.offload.submit(on_full: :raise) do
               commit_failed(activation, activation.invocation, start_error)
             end
             commit.on_complete do |terminal, commit_error|
@@ -107,7 +107,7 @@ module Phronomy
 
       # Persists all Runtime events from the previous call, fixes the next
       # Canonical LLM Input Manifest, and materializes the next Runtime Projection.
-      # This method is executed on the blocking adapter pool, never on EventLoop.
+      # This method is executed on an OffloadPool worker, never on EventLoop.
       def prepare_next_llm_call(activation)
         snapshot = activation.runtime_snapshot
         manifest = manifest_ref = updated = root = nil
@@ -397,7 +397,7 @@ module Phronomy
 
       def finish(activation, result_task, invocation, error)
         runtime = Phronomy::Runtime.instance
-        operation = runtime.blocking_io.submit do
+        operation = runtime.offload.submit(on_full: :raise) do
           compute_terminal(activation, invocation, error)
         end
         operation.on_complete do |outcome, commit_error|
@@ -1069,7 +1069,7 @@ module Phronomy
       def dispatch_approval_listener(invocation, request)
         listener = invocation.approval_listener
         return unless listener
-        Phronomy::Runtime.instance.blocking_io.submit { listener.call(request) }
+        Phronomy::Runtime.instance.offload.submit(on_full: :raise) { listener.call(request) }
       end
 
       def json_value(value)

data/lib/phronomy/agent/shared_state.rb

@@ -144,6 +144,7 @@ module Phronomy
           tool_name "read_store"
           description "Read all current findings from the shared knowledge store. " \
             "Call this to see what other researchers have discovered."
+          execution_mode :cooperative
 
           define_method(:execute) { store.read_all.to_json }
         end
@@ -152,6 +153,7 @@ module Phronomy
           tool_name "write_finding"
           description "Record a new finding into the shared knowledge store so " \
             "that other researchers can build on your discovery."
+          execution_mode :cooperative
           param :content, type: :string, desc: "The finding to record"
 
           define_method(:execute) do |content:|

data/lib/phronomy/agent/tool_executor.rb

@@ -2,90 +2,48 @@
 
 module Phronomy
   module Agent
-    # Centralises Tool execution routing based on execution_mode.
+    # Routes Tool work according to the Tool execution contract.
     #
-    # Tool-specific timeout and retry belong to the Tool implementation or its
-    # underlying client. This executor only chooses the Phronomy execution
-    # resource and propagates cooperative cancellation.
-    # @api private
+    # :cooperative Tool calls execute inline and must return quickly. call_async
+    # wraps their result in an already-settled Task and never consumes an
+    # OffloadPool worker.
+    #
+    # :offloaded Tool calls route synchronous work through OffloadPool. Phronomy
+    # does not distinguish whether the reason is blocking I/O, CPU-bound work, or
+    # another long synchronous operation.
     module ToolExecutor
-      WARNED_MODES = Set.new
-      WARNED_MODES_MUTEX = Mutex.new
-      private_constant :WARNED_MODES, :WARNED_MODES_MUTEX
-
-      # Agent-owned execution boundary. Only a ToolInvocation that has consumed
-      # authorization may enter this method.
-      def self.call_invocation_async(
-        tool_invocation:,
-        cancellation_token: nil,
-        config: {},
-        runtime: Phronomy::Runtime.instance
-      )
-        unless tool_invocation.dispatchable?
-          raise Phronomy::ToolError,
-            "ToolInvocation #{tool_invocation.id} is not authorized for dispatch"
-        end
-
-        call_async(
-          tool: tool_invocation.tool,
-          args: tool_invocation.arguments,
-          cancellation_token: cancellation_token,
-          config: config,
-          runtime: runtime
-        )
-      end
-
-      # Low-level Tool API used by direct Tool#call_async callers. Agent execution
-      # must use .call_invocation_async so authorization cannot be bypassed.
-      #
-      # +config+ remains available for invocation metadata, but Phronomy does not
-      # interpret it as a Tool timeout or retry policy.
       def self.call_async(
         tool:,
         args:,
         cancellation_token: nil,
         config: {},
-        runtime: Phronomy::Runtime.instance
+        runtime: nil,
+        on_full: :raise
       )
-        ct = cancellation_token
         mode = tool.class.execution_mode
 
-        if mode == :cpu_bound || mode == :external_process
-          warn_key = [tool.class.name, mode]
-          newly_warned = WARNED_MODES_MUTEX.synchronize { WARNED_MODES.add?(warn_key) }
-          if newly_warned
-            message = if mode == :cpu_bound
-              "[Phronomy] Tool #{tool.class.name} declares execution_mode :cpu_bound, " \
-                "which has no dedicated executor. Falling back to blocking_io " \
-                "(BlockingAdapterPool). Use :blocking_io explicitly to suppress this warning."
-            else
-              "[Phronomy] Tool #{tool.class.name} declares execution_mode :external_process, " \
-                "which has no dedicated process manager. Falling back to blocking_io " \
-                "(BlockingAdapterPool)."
-            end
-            if Phronomy.configuration.logger
-              Phronomy.configuration.logger.warn(message)
-            else
-              warn message
-            end
+        case mode
+        when :cooperative
+          task = Phronomy::Task.deferred(name: "tool-#{tool.name}")
+          begin
+            task.complete(
+              tool.call(args, cancellation_token: cancellation_token)
+            )
+          rescue => error
+            task.fail(error)
           end
-          mode = :blocking_io
-        end
-
-        pool = begin
-          runtime&.blocking_io
-        rescue
-          nil
-        end
-
-        if mode == :cooperative || pool.nil?
-          runtime.spawn(name: "tool-#{tool.class.name.to_s.split("::").last}") do
-            tool.call(args, cancellation_token: ct)
+          task
+        when :offloaded
+          runtime ||= Phronomy::Runtime.instance
+          runtime.offload.submit(
+            cancellation_token: cancellation_token,
+            on_full: on_full
+          ) do
+            tool.call(args, cancellation_token: cancellation_token)
           end
         else
-          pool.submit(cancellation_token: ct) do
-            tool.call(args, cancellation_token: ct)
-          end
+          raise Phronomy::ConfigurationError,
+            "unknown Tool execution_mode: #{mode.inspect}"
         end
       end
     end

data/lib/phronomy/agent/tool_invocation.rb

@@ -119,8 +119,7 @@ module Phronomy
         end
 
         if schema_error
-          if @tool.class.respond_to?(:on_schema_error) &&
-              @tool.class.on_schema_error == :raise
+          if @tool.class.respond_to?(:on_schema_error) && @tool.class.on_schema_error == :raise
             @error = Phronomy::ToolError.new(
               "#{@tool.class.name} schema error: #{schema_error}"
             )
@@ -141,64 +140,75 @@ module Phronomy
         self
       end
 
-      def authorization_task(runtime: Phronomy::Runtime.instance)
+      # Starts authorization and reports exactly one AuthorizationOutcome through
+      # the callback. No Task is created.
+      def start_authorization(runtime: Phronomy::Runtime.instance, &callback)
+        raise ArgumentError, "start_authorization requires a callback" unless callback
+
         pool = runtime.pool(
           :authorization,
           size: Phronomy.configuration.authorization_pool_size,
           queue_size: Phronomy.configuration.authorization_queue_size
         )
-        timeout = @config.fetch(:authorization_timeout, Phronomy.configuration.authorization_timeout)
-        pending = pool.submit(
+        timeout = @config.fetch(
+          :authorization_timeout,
+          Phronomy.configuration.authorization_timeout
+        )
+        operation = pool.submit(
           timeout: timeout,
           cancellation_token: @config[:cancellation_token],
           on_full: :raise
         ) { evaluate_authorization }
-
-        task = Phronomy::Task.deferred(name: "tool-authorization:#{@tool_name}")
-        pending.on_complete do |outcome, error|
-          resolved = error ? authorization_failure_outcome(error) : outcome
-          task.backend.unblock(resolved, nil)
-          task.transition!(:completed, value: resolved)
+        operation.on_complete do |outcome, error|
+          callback.call(error ? authorization_failure_outcome(error) : outcome)
         end
-        task
+        self
       rescue => error
-        task = Phronomy::Task.deferred(name: "tool-authorization:#{@tool_name}")
-        outcome = authorization_failure_outcome(error)
-        task.backend.unblock(outcome, nil)
-        task.transition!(:completed, value: outcome)
-        task
+        callback.call(authorization_failure_outcome(error))
+        self
       end
 
-      def execution_task(runtime: Phronomy::Runtime.instance)
-        pending = Phronomy::Agent::ToolExecutor.call_invocation_async(
-          tool_invocation: self,
-          cancellation_token: @config[:cancellation_token],
-          config: @config,
-          runtime: runtime
-        )
-        task = Phronomy::Task.deferred(name: "tool-execution:#{@tool_name}")
-        pending.on_complete do |result, error|
-          outcome = if error
-            ExecutionOutcome.new(
-              error: error,
-              cancelled: error.is_a?(Phronomy::CancellationError)
-            )
-          else
-            ExecutionOutcome.new(result: result)
+      # Starts Tool execution and reports completion through the callback.
+      #
+      # Both core execution paths use Tool#call_async:
+      #
+      # - :cooperative returns a Task without consuming an OffloadPool worker.
+      #   Ordinary cooperative Tools settle that Task inline; Agent-backed Tools
+      #   may start child EventLoop/FSM work and settle later.
+      # - :offloaded returns an OffloadPool PendingOperation for synchronous work
+      #   that must not occupy the EventLoop.
+      #
+      # In either case ToolInvocation remains in :running and resumes only from
+      # the explicit :execution_completed FSM event posted by the session builder.
+      def start_execution(runtime: Phronomy::Runtime.instance, &callback)
+        raise ArgumentError, "start_execution requires a callback" unless callback
+        unless dispatchable?
+          callback.call(ExecutionOutcome.new(error: Phronomy::ToolError.new(
+            "ToolInvocation #{@id} is not authorized for dispatch"
+          )))
+          return self
+        end
+
+        case @tool.class.execution_mode
+        when :cooperative, :offloaded
+          operation = start_async_tool_operation(runtime)
+          unless operation.respond_to?(:on_complete)
+            raise Phronomy::ToolError,
+              "Tool #{@tool.class.name}#call_async must return a completion handle"
           end
-          task.backend.unblock(outcome, nil)
-          task.transition!(:completed, value: outcome)
+
+          operation.on_complete do |result, error|
+            callback.call(execution_outcome(result, error))
+          end
+        else
+          callback.call(ExecutionOutcome.new(error: Phronomy::ConfigurationError.new(
+            "unknown Tool execution_mode: #{@tool.class.execution_mode.inspect}"
+          )))
         end
-        task
+        self
       rescue => error
-        task = Phronomy::Task.deferred(name: "tool-execution:#{@tool_name}")
-        outcome = ExecutionOutcome.new(
-          error: error,
-          cancelled: error.is_a?(Phronomy::CancellationError)
-        )
-        task.backend.unblock(outcome, nil)
-        task.transition!(:completed, value: outcome)
-        task
+        callback.call(execution_outcome(nil, error))
+        self
       end
 
       def mark_awaiting_approval! = (@status = :awaiting_approval
@@ -256,6 +266,48 @@ module Phronomy
 
       private
 
+      # Runtime is framework execution infrastructure, not part of the public
+      # Tool#call_async protocol.
+      #
+      # Tools using Capability::Base's default async implementation are routed
+      # directly through ToolExecutor so this ToolInvocation can supply its
+      # owning Runtime internally. Tools that override #call_async (for example
+      # Agent-backed Tools) receive only the public Tool async keywords.
+      def start_async_tool_operation(runtime)
+        if uses_default_call_async?
+          Phronomy::Agent::ToolExecutor.call_async(
+            tool: @tool,
+            args: @arguments,
+            cancellation_token: @config[:cancellation_token],
+            config: @config,
+            runtime: runtime,
+            on_full: :raise
+          )
+        else
+          @tool.call_async(
+            @arguments,
+            cancellation_token: @config[:cancellation_token],
+            config: @config
+          )
+        end
+      end
+
+      def uses_default_call_async?
+        @tool.method(:call_async).owner ==
+          Phronomy::Agent::Context::Capability::Base
+      end
+
+      def execution_outcome(result, error)
+        if error
+          ExecutionOutcome.new(
+            error: error,
+            cancelled: error.is_a?(Phronomy::CancellationError)
+          )
+        else
+          ExecutionOutcome.new(result: result)
+        end
+      end
+
       def evaluate_authorization
         request = build_request(facts: {}, default_decision: nil)
         facts = evaluate_facts
@@ -272,9 +324,7 @@ module Phronomy
         end
 
         reason = if decision == :require_approval
-          (@origin == :mcp) ?
-            "MCP Tool execution requires approval" :
-            "Tool execution requires approval"
+          (@origin == :mcp) ? "MCP Tool execution requires approval" : "Tool execution requires approval"
         end
         AuthorizationOutcome.new(decision: decision, facts: facts, reason: reason)
       end