phronomy 0.17.0 → 0.19.0

data/lib/phronomy/tools/agent.rb

@@ -2,11 +2,17 @@
 
 module Phronomy
   module Tools
-    # Wraps a Phronomy::Agent::Base subclass as a callable tool so that a parent
-    # agent can delegate a one-shot sub-task through the same stateful pipeline.
+    # Wraps a Phronomy::Agent::Base subclass as a callable Tool.
+    #
+    # Agent-backed Tools are logically asynchronous rather than offloaded
+    # synchronous operations. Their ToolInvocation starts the child Agent and then
+    # returns to EventLoop immediately; the Tool completion handle settles when the
+    # child Agent FSMSession finishes. An OffloadPool worker is therefore never
+    # consumed merely to wait for another Agent.
     class Agent < Phronomy::Agent::Context::Capability::Base
-      description "Wraps an agent as a tool"
-      param :input, type: :string, desc: "The input to forward to the wrapped agent"
+      execution_mode :cooperative
+      description "Wraps a Phronomy::Agent as a Tool"
+      param :input, type: :string, desc: "The input to forward to the wrapped Agent"
 
       class << self
         def from_agent(agent_class, tool_name: nil, description: nil)
@@ -25,13 +31,38 @@ module Phronomy
 
           klass.tool_name(effective_name)
           klass.description(effective_desc)
-          klass.define_method(:execute) do |input:|
+
+          # Preserve the synchronous Tool API for top-level callers. ToolInvocation
+          # never uses this path for Agent-backed Tools; it calls #call_async.
+          klass.define_method(:execute) do |input:, cancellation_token: nil|
+            invoke_options = {}
+            if cancellation_token
+              invoke_options[:config] = {cancellation_token: cancellation_token}
+            end
             result = Phronomy::Agent.run_once(
               definition: agent_class,
-              input: input
+              input: input,
+              **invoke_options
             )
             result[:output].to_s
           end
+
+          # Internal asynchronous execution protocol used by Agent#call_async.
+          # The child Agent owns its own FSMSession/EventLoop lifecycle; this
+          # method only returns its completion handle and performs a short map.
+          klass.define_method(:execute_async) do |input:, cancellation_token: nil, config: {}|
+            persistence = Phronomy::Persistence::InMemory.new
+            agent = agent_class.create(persistence: persistence)
+            task_config = (config || {}).dup
+            if cancellation_token && !task_config[:cancellation_token]
+              task_config[:cancellation_token] = cancellation_token
+            end
+
+            agent.invoke_async(input, config: task_config).map do |result|
+              result[:output].to_s
+            end
+          end
+          klass.send(:private, :execute_async)
           klass
         end
 
@@ -49,6 +80,110 @@ module Phronomy
             .sub(/_tool$/, "")
         end
       end
+
+      # Agent-backed Tools have an asynchronous implementation that does not use
+      # ToolExecutor/OffloadPool. Validation and Tool error policy still match
+      # Capability::Base#call.
+      def call_async(
+        args,
+        cancellation_token: nil,
+        config: {}
+      )
+        cancellation_token&.raise_if_cancelled!
+        validated_args, schema_error = send(:validate_and_coerce, args)
+
+        if schema_error
+          return schema_error_task(schema_error)
+        end
+
+        source = execute_async(
+          **(validated_args || {}),
+          cancellation_token: cancellation_token,
+          config: config || {}
+        )
+        unless source.respond_to?(:on_complete)
+          raise Phronomy::ToolError,
+            "#{self.class.name} asynchronous execution must return a completion handle"
+        end
+
+        result_task = Phronomy::Task.deferred(name: "agent-tool-#{name}")
+        source.on_complete do |result, error|
+          if error
+            settle_async_error(result_task, error)
+            next
+          end
+
+          begin
+            result_task.complete(send(:truncate_result_if_needed, result))
+          rescue => result_error
+            settle_async_error(result_task, result_error)
+          end
+        end
+        result_task
+      rescue Phronomy::ToolError, Phronomy::CancellationError => error
+        failed_task(error)
+      rescue => error
+        result_task = Phronomy::Task.deferred(name: "agent-tool-#{name}")
+        settle_async_error(result_task, error)
+        result_task
+      end
+
+      private
+
+      # Subclasses created by .from_agent and Orchestrator override this method.
+      # It deliberately remains private so it is not part of the public Tool API.
+      def execute_async(input:, cancellation_token: nil, config: {})
+        task = Phronomy::Task.deferred(name: "agent-tool-#{name}-fallback")
+        begin
+          task.complete(execute(input: input, cancellation_token: cancellation_token))
+        rescue => error
+          task.fail(error)
+        end
+        task
+      end
+
+      def schema_error_task(schema_error)
+        task = Phronomy::Task.deferred(name: "agent-tool-#{name}-schema")
+        if self.class.on_schema_error == :raise
+          task.fail(Phronomy::ToolError.new(
+            "#{self.class.name} schema error: #{schema_error}"
+          ))
+        else
+          task.complete("Schema validation failed: #{schema_error}")
+        end
+        task
+      end
+
+      def failed_task(error)
+        Phronomy::Task.deferred(name: "agent-tool-#{name}-failed").tap do |task|
+          task.fail(error)
+        end
+      end
+
+      def settle_async_error(task, error)
+        if error.is_a?(Phronomy::ToolError) || error.is_a?(Phronomy::CancellationError)
+          task.fail(error)
+          return task
+        end
+
+        if self.class.on_error == :suppress
+          message = "[Phronomy] Tool #{self.class.name} suppressed error: " \
+            "#{error.class}: #{error.message}"
+          if Phronomy.configuration.logger
+            Phronomy.configuration.logger.warn(message)
+          else
+            warn message
+          end
+          task.complete("Tool error suppressed: #{error.message}")
+        else
+          wrapped = Phronomy::ToolError.new(
+            "#{self.class.name} execution failed: #{error.message}"
+          )
+          wrapped.set_backtrace(error.backtrace)
+          task.fail(wrapped)
+        end
+        task
+      end
     end
   end
 end

data/lib/phronomy/vector_store/async_backend.rb

@@ -7,7 +7,7 @@ module Phronomy
     # Mixing this module into a VectorStore class provides three choices:
     #
     # 1. **Do nothing** — inherits default implementations from {VectorStore::Base}
-    #    that route through {BlockingAdapterPool} (the previous behaviour).
+    #    that route through {OffloadPool}.
     #
     # 2. **Override selectively** — override only the async methods where the
     #    backend has a native async driver, while the remaining methods fall back
@@ -30,7 +30,7 @@ module Phronomy
     module AsyncBackend
       # Async variant of {VectorStore::Base#add}.
       #
-      # Submits the add call to {BlockingAdapterPool} by default.
+      # Submits the add call to {OffloadPool} by default.
       # Override to use a native async driver.
       #
       # @param id                 [String]
@@ -38,12 +38,13 @@ module Phronomy
       # @param metadata           [Hash]
       # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil]
       # @param timeout            [Numeric, nil]
-      # @return [BlockingAdapterPool::PendingOperation]
+      # @return [OffloadPool::PendingOperation]
       # @api public
       def add_async(id:, embedding:, metadata: {}, cancellation_token: nil, timeout: nil)
-        Phronomy::Runtime.instance.blocking_io.submit(
+        Phronomy::Runtime.instance.offload.submit(
           timeout: timeout,
-          cancellation_token: cancellation_token
+          cancellation_token: cancellation_token,
+          on_full: :raise
         ) do
           add(id: id, embedding: embedding, metadata: metadata, cancellation_token: cancellation_token)
         end
@@ -51,19 +52,20 @@ module Phronomy
 
       # Async variant of {VectorStore::Base#search}.
       #
-      # Submits the search call to {BlockingAdapterPool} by default.
+      # Submits the search call to {OffloadPool} by default.
       # Override to use a native async driver.
       #
       # @param query_embedding    [Array<Float>]
       # @param k                  [Integer]
       # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil]
       # @param timeout            [Numeric, nil]
-      # @return [BlockingAdapterPool::PendingOperation]
+      # @return [OffloadPool::PendingOperation]
       # @api public
       def search_async(query_embedding:, k: 5, cancellation_token: nil, timeout: nil)
-        Phronomy::Runtime.instance.blocking_io.submit(
+        Phronomy::Runtime.instance.offload.submit(
           timeout: timeout,
-          cancellation_token: cancellation_token
+          cancellation_token: cancellation_token,
+          on_full: :raise
         ) do
           search(query_embedding: query_embedding, k: k, cancellation_token: cancellation_token)
         end
@@ -71,18 +73,19 @@ module Phronomy
 
       # Async variant of {VectorStore::Base#remove}.
       #
-      # Submits the remove call to {BlockingAdapterPool} by default.
+      # Submits the remove call to {OffloadPool} by default.
       # Override to use a native async driver.
       #
       # @param id                 [String]
       # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil]
       # @param timeout            [Numeric, nil]
-      # @return [BlockingAdapterPool::PendingOperation]
+      # @return [OffloadPool::PendingOperation]
       # @api public
       def remove_async(id:, cancellation_token: nil, timeout: nil)
-        Phronomy::Runtime.instance.blocking_io.submit(
+        Phronomy::Runtime.instance.offload.submit(
           timeout: timeout,
-          cancellation_token: cancellation_token
+          cancellation_token: cancellation_token,
+          on_full: :raise
         ) do
           remove(id: id)
         end
@@ -90,17 +93,18 @@ module Phronomy
 
       # Async variant of {VectorStore::Base#clear}.
       #
-      # Submits the clear call to {BlockingAdapterPool} by default.
+      # Submits the clear call to {OffloadPool} by default.
       # Override to use a native async driver.
       #
       # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil]
       # @param timeout            [Numeric, nil]
-      # @return [BlockingAdapterPool::PendingOperation]
+      # @return [OffloadPool::PendingOperation]
       # @api public
       def clear_async(cancellation_token: nil, timeout: nil)
-        Phronomy::Runtime.instance.blocking_io.submit(
+        Phronomy::Runtime.instance.offload.submit(
           timeout: timeout,
-          cancellation_token: cancellation_token
+          cancellation_token: cancellation_token,
+          on_full: :raise
         ) do
           clear
         end

data/lib/phronomy/vector_store/base.rb

@@ -9,8 +9,8 @@ module Phronomy
     #
     # Async methods (`search_async`, `add_async`, `remove_async`, `clear_async`)
     # are provided by the {AsyncBackend} mixin which defaults to routing calls
-    # through {BlockingAdapterPool}.  Backends with native async drivers may
-    # override individual async methods without touching the pool at all.
+    # through {OffloadPool}. Backends with native async drivers may override
+    # individual async methods without touching the pool at all.
     class Base
       include AsyncBackend
 

data/lib/phronomy/vector_store/embeddings/base.rb

@@ -19,18 +19,19 @@ module Phronomy
           raise NotImplementedError, "#{self.class}#embed is not implemented"
         end
 
-        # Submits an {#embed} call to {BlockingAdapterPool} and returns a
-        # {BlockingAdapterPool::PendingOperation}.
+        # Submits an {#embed} call to {OffloadPool} and returns an
+        # {OffloadPool::PendingOperation}.
         #
         # @param text               [String]
         # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil]
         # @param timeout            [Numeric, nil] seconds before the operation is abandoned
-        # @return [BlockingAdapterPool::PendingOperation]
+        # @return [OffloadPool::PendingOperation]
         # @api public
         def embed_async(text, cancellation_token = nil, timeout: nil)
-          Phronomy::Runtime.instance.blocking_io.submit(
+          Phronomy::Runtime.instance.offload.submit(
             timeout: timeout,
-            cancellation_token: cancellation_token
+            cancellation_token: cancellation_token,
+            on_full: :raise
           ) do
             embed(text, cancellation_token)
           end

data/lib/phronomy/version.rb

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

data/lib/phronomy/workflow.rb

@@ -8,8 +8,8 @@ module Phronomy
   class Workflow
     include Phronomy::Runnable
 
-    def self.define(context_class, state_store: nil, &block)
-      builder = Builder.new(context_class, state_store: state_store)
+    def self.define(context_class, persistence: nil, &block)
+      builder = Builder.new(context_class, persistence: persistence)
       builder.instance_eval(&block)
       builder.build
     end
@@ -41,12 +41,13 @@ module Phronomy
       @runner.send_event(state: state, event: event, input: input)
     end
 
-    # Sends an event to an active Workflow session without blocking.
+    # Sends an event to an active Workflow execution without blocking.
     #
-    # This method is safe to call from an Agent/Tool listener running on the
-    # EventLoop thread because it only enqueues a later dispatch.
+    # +thread_id+ is the logical/durable Workflow identity. EventLoop resolves it
+    # to the currently owning Runtime-only fsm_session_id. InvocationContext's
+    # application session_id is unrelated to this routing.
     #
-    # @return [Boolean] true when admitted; false when the session is not live
+    # @return [Boolean] true when admitted; false when the Workflow is not live
     #   or Runtime shutdown has begun
     # @api public
     def signal(thread_id:, event:, payload: nil)
@@ -76,9 +77,9 @@ module Phronomy
     class Builder
       FINISH = Phronomy::WorkflowRunner::FINISH
 
-      def initialize(context_class, state_store: nil)
+      def initialize(context_class, persistence: nil)
         @context_class = context_class
-        @state_store = state_store
+        @persistence = persistence
         @initial = nil
         @declared_states = []
         @entry_actions = {}
@@ -167,7 +168,7 @@ module Phronomy
           external_events: external_events,
           entry_point: @initial || @declared_states.first,
           wait_state_names: @wait_state_names.dup,
-          state_store: @state_store
+          persistence: @persistence
         )
         Workflow.new(runner)
       end