phronomy 0.6.0 → 0.7.1

data/lib/phronomy/agent/before_completion_context.rb

@@ -35,6 +35,7 @@ module Phronomy
       # @param messages [Array]
       # @param config   [Hash]
       # @param params   [Hash] initial params (model, temperature already set on chat)
+      # @api public
       def initialize(agent:, messages:, config:, params: {})
         @agent = agent
         @messages = messages.dup.freeze

data/lib/phronomy/agent/checkpoint.rb

@@ -47,6 +47,7 @@ module Phronomy
       # @param pending_tool_name    [String]
       # @param pending_tool_args    [Hash]
       # @param pending_tool_call_id [String]
+      # @api public
       def initialize(thread_id:, original_input:, messages:, pending_tool_name:, pending_tool_args:, pending_tool_call_id:)
         @thread_id = thread_id
         @original_input = original_input

data/lib/phronomy/agent/concerns/before_completion.rb

@@ -8,6 +8,7 @@ module Phronomy
       # Included in {Phronomy::Agent::Base}. Hooks are executed just before every
       # LLM call (global → class → instance order) and may inject or override
       # LLM parameters such as temperature or model.
+      # @api private
       module BeforeCompletion
         def self.included(base)
           base.extend(ClassMethods)
@@ -26,6 +27,7 @@ module Phronomy
           #   class MyAgent < Phronomy::Agent::Base
           #     before_completion ->(ctx) { { temperature: 0.2 } }
           #   end
+          # @api private
           def before_completion(callable = nil)
             if callable.nil? && !block_given?
               @before_completion
@@ -35,6 +37,7 @@ module Phronomy
           end
 
           # @return [#call, nil]
+          # @api private
           def _before_completion
             @before_completion
           end
@@ -53,6 +56,7 @@ module Phronomy
         # @param chat   [RubyLLM::Chat] the assembled chat object
         # @param config [Hash] the invocation config hash
         # @return [Hash] the merged params applied to the chat
+        # @api private
         def run_before_completion_hooks!(chat, config)
           hooks = [
             Phronomy.configuration.before_completion,
@@ -72,6 +76,7 @@ module Phronomy
           merged = {}
           hooks.each do |hook|
             result = hook.call(ctx)
+            check_cancellation!(config, "invocation cancelled during before_completion hook")
             merged.merge!(result) if result.is_a?(Hash)
           end
 
@@ -86,6 +91,7 @@ module Phronomy
         #
         # @param chat   [RubyLLM::Chat]
         # @param params [Hash]
+        # @api private
         def apply_before_completion_params!(chat, params)
           params.each do |key, value|
             case key

data/lib/phronomy/agent/concerns/error_translation.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    module Concerns
+      # Translates RubyLLM transport errors into the corresponding Phronomy error
+      # classes so that callers can rescue Phronomy-namespaced exceptions rather
+      # than coupling themselves to the underlying provider library.
+      #
+      # Included in {Phronomy::Agent::Base}.
+      module ErrorTranslation
+        private
+
+        # Re-raises +error+ as the most specific Phronomy error class that
+        # corresponds to it.  Non-RubyLLM errors are re-raised unchanged.
+        # The original exception is available as +#cause+ on the translated error.
+        #
+        # Must be called from within an active +rescue+ block so that Ruby
+        # automatically sets +#cause+ on the new exception.
+        #
+        # @param error [Exception]
+        # @raise [Phronomy::RateLimitError] for provider HTTP 429
+        # @raise [Phronomy::AuthenticationError] for provider HTTP 401 / 403
+        # @raise [Phronomy::ContextLengthError] for context window overflow
+        # @raise [Phronomy::TransportError] for all other +RubyLLM::Error+ subclasses
+        # @raise re-raises +error+ unchanged for non-RubyLLM exceptions
+        # @api private
+        def translate_and_reraise!(error)
+          case error
+          when RubyLLM::RateLimitError
+            raise Phronomy::RateLimitError, error.message
+          when RubyLLM::UnauthorizedError, RubyLLM::ForbiddenError
+            raise Phronomy::AuthenticationError, error.message
+          when RubyLLM::ContextLengthExceededError
+            raise Phronomy::ContextLengthError, error.message
+          when RubyLLM::Error
+            raise Phronomy::TransportError, error.message
+          else
+            raise # bare re-raise preserves $! and its backtrace unchanged
+          end
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/agent/concerns/guardrailable.rb

@@ -8,10 +8,12 @@ module Phronomy
       # Included in {Phronomy::Agent::Base}. Guardrails are run on the raw
       # input string before the LLM is called, and on the raw output string
       # before the result is returned to the caller.
+      # @api private
       module Guardrailable
         # Attach a guardrail that validates input before every #invoke call.
         # @param guardrail [Phronomy::Guardrail::InputGuardrail]
         # @return [self]
+        # @api private
         def add_input_guardrail(guardrail)
           @input_guardrails ||= []
           @input_guardrails << guardrail
@@ -21,6 +23,7 @@ module Phronomy
         # Attach a guardrail that validates output before it is returned.
         # @param guardrail [Phronomy::Guardrail::OutputGuardrail]
         # @return [self]
+        # @api private
         def add_output_guardrail(guardrail)
           @output_guardrails ||= []
           @output_guardrails << guardrail

data/lib/phronomy/agent/concerns/retryable.rb

@@ -7,6 +7,7 @@ module Phronomy
       #
       # Included in {Phronomy::Agent::Base}. The retry loop wraps the full
       # #invoke_once call; {Phronomy::GuardrailError} is never retried.
+      # @api private
       module Retryable
         def self.included(base)
           base.extend(ClassMethods)
@@ -25,6 +26,7 @@ module Phronomy
           #   class MyAgent < Phronomy::Agent::Base
           #     retry_policy times: 2, wait: :exponential, base: 1.0
           #   end
+          # @api private
           def retry_policy(times: 0, wait: 0, base: 1.0)
             @_retry_policy = {times: times, wait: wait, base: base}
           end
@@ -35,6 +37,7 @@ module Phronomy
 
           # Injectable sleep callable for testing (shared with Tool::Base pattern).
           # @return [#call]
+          # @api private
           def _sleep_proc
             @_sleep_proc || method(:sleep)
           end
@@ -48,12 +51,19 @@ module Phronomy
 
         # Retry loop for #invoke. Separated so that ReactAgent can override #invoke_once.
         def _invoke_impl(input, messages: [], thread_id: nil, config: {})
+          # Fail fast when the token is already cancelled before any LLM call.
+          if (token = config[:cancellation_token]) && token.cancelled?
+            raise Phronomy::CancellationError, "invocation cancelled"
+          end
+
           policy = self.class._retry_policy
           attempt = 0
           begin
             invoke_once(input, messages: messages, thread_id: thread_id, config: config)
           rescue Phronomy::GuardrailError
             raise
+          rescue Phronomy::CancellationError
+            raise # Never retry after cancellation.
           rescue
             if policy && attempt < policy[:times]
               wait = compute_agent_retry_wait(policy[:wait], policy[:base], attempt)
@@ -61,7 +71,7 @@ module Phronomy
               attempt += 1
               retry
             end
-            raise
+            translate_and_reraise!($!)
           end
         end
 
@@ -70,6 +80,7 @@ module Phronomy
         # @param base     [Float]
         # @param attempt  [Integer]
         # @return [Float]
+        # @api private
         def compute_agent_retry_wait(strategy, base, attempt)
           case strategy
           when :exponential

data/lib/phronomy/agent/concerns/suspendable.rb

@@ -8,6 +8,7 @@ module Phronomy
       # Included in {Phronomy::Agent::Base}. When a tool decorated with
       # +requires_approval true+ is called and no synchronous approval handler
       # has been registered, the invocation is suspended and a
+      # @api private
       # {Phronomy::Agent::Checkpoint} is returned so the caller can resume later.
       module Suspendable
         # Registers a callback that is invoked before executing any tool that has
@@ -25,11 +26,27 @@ module Phronomy
         #   agent = MyAgent.new
         #   agent.on_approval_required { |tool_name, args| prompt_user(tool_name, args) }
         # @return [self]
+        # @api private
         def on_approval_required(&block)
           @approval_handler = block
           self
         end
 
+        # Registers a scope policy callable for this agent instance.
+        #
+        # The callable receives +(tool_class, scope, agent)+ and must return
+        # +:allow+, +:reject+, or +:approve+.
+        #
+        # @example Reject all write-scoped tools
+        #   agent.scope_policy = ->(_tc, scope, _agent) { scope == :write ? :reject : :allow }
+        #
+        # @param policy [#call]
+        # @return [void]
+        # @api public
+        def scope_policy=(policy)
+          @scope_policy = policy
+        end
+
         # Resumes a previously suspended invocation from a {Phronomy::Agent::Checkpoint}.
         #
         # This method reconstructs the conversation state captured at suspension
@@ -43,6 +60,7 @@ module Phronomy
         # @param config     [Hash] same runtime options as #invoke
         # @return [Hash] +{ output: String, suspended: false, messages: Array, usage: Phronomy::TokenUsage }+
         # @raise [Phronomy::GuardrailError] when an output guardrail rejects the value
+        # @api private
         def resume(checkpoint, approved:, config: {})
           # Build a fresh chat with all tools registered.
           chat = build_chat
@@ -95,6 +113,7 @@ module Phronomy
         #   - none of the agent's tools have requires_approval set.
         #
         # @param chat [RubyLLM::Chat]
+        # @api private
         def _register_suspension_hook!(chat)
           return if @approval_handler
           return if self.class.tools.none? { |tc| tc.requires_approval }

data/lib/phronomy/agent/fsm.rb

@@ -15,14 +15,14 @@ module Phronomy
     # == Execution model
     #
     # {#start} is called by the EventLoop on the +:start+ event.  It immediately
-    # returns after spawning a background IO thread that runs the agent's full
+    # returns after spawning a {Phronomy::Task} that runs the agent's full
     # invocation pipeline (via +_invoke_impl+).  The EventLoop thread is never
     # blocked by agent execution.
     #
-    # Inside the IO thread, the +:phronomy_agent_parallel_tools+ thread-local
-    # flag is set to +true+ so that {Agent::Base#build_chat} returns a
-    # {ParallelToolChat} instance, enabling concurrent tool dispatch when the LLM
-    # returns multiple tool calls in one response.
+    # Inside the task, {Agent::Base#build_chat} returns a
+    # {ParallelToolChat} instance when EventLoop mode is enabled, allowing
+    # concurrent tool dispatch when the LLM returns multiple tool calls in one
+    # response.
     #
     # == Completion events
     #
@@ -57,6 +57,7 @@ module Phronomy
     # {Agent::Base#run_as_child} creates an +AgentFSM+ with +parent_id+ set to
     # +ctx.thread_id+, registers it with the EventLoop, and returns immediately.
     # The parent {FSMSession} waits for the +:child_completed+ event.
+    # @api private
     class FSM
       # @return [String] unique identifier used as the EventLoop target_id
       attr_reader :id
@@ -71,39 +72,30 @@ module Phronomy
       #                                           auto-generated when nil
       # @param config    [Hash]                   invocation config forwarded to
       #                                           +_invoke_impl+
-      # @param parent_id    [String, nil]  EventLoop id of the parent
-      #                                     FSMSession; when set, a
-      #                                     +:child_completed+ event is posted
-      #                                     on completion
-      # @param result_writer [Proc, nil]   optional callable invoked with the
-      #                                     result hash <b>before</b>
-      #                                     +:child_completed+ is posted.
-      #                                     Use this to write the agent output
-      #                                     back into the parent WorkflowContext.
-      #                                     Thread::Queue provides the
-      #                                     happens-before guarantee.
+      # @param parent_id [String, nil]  EventLoop id of the parent FSMSession;
+      #                                  when set, a +:child_completed+ event
+      #                                  is posted on completion.  The result
+      #                                  is delivered exclusively as the event
+      #                                  payload — no cross-thread writes to the
+      #                                  parent WorkflowContext are performed.
       #
-      # @example Writing result into context
-      #   entry :run_agent, ->(ctx) {
-      #     MyAgent.new.run_as_child(ctx.query, ctx: ctx) { |r| ctx.answer = r[:output] }
-      #   }
-      def initialize(agent:, input:, messages: [], thread_id: nil, config: {}, parent_id: nil, result_writer: nil)
+      # @api private
+      def initialize(agent:, input:, messages: [], thread_id: nil, config: {}, parent_id: nil)
         @agent = agent
         @input = input
         @messages = Array(messages).dup
         @thread_id = thread_id || SecureRandom.uuid
         @config = config
         @parent_id = parent_id
-        @result_writer = result_writer
         @id = @thread_id
         @current_phase = :idle
       end
 
       # Called by {EventLoop} on the +:start+ event.
-      # Transitions to +:running+ and spawns the agent IO thread.
+      # Transitions to +:running+ and spawns the agent task.
       def start
         @current_phase = :running
-        spawn_agent_thread
+        spawn_agent_task
       end
 
       # Called by {EventLoop} for external events dispatched to this id.
@@ -115,10 +107,10 @@ module Phronomy
 
       private
 
-      # Spawns the background IO thread that runs the agent invocation.
-      # Captures all instance variables by value so the thread closure is
+      # Spawns a {Phronomy::Task} that runs the agent invocation pipeline.
+      # Captures all instance variables by value so the task closure is
       # safe even if the FSM object is modified (though it is not in practice).
-      def spawn_agent_thread
+      def spawn_agent_task
         agent = @agent
         input = @input
         messages = @messages
@@ -126,38 +118,38 @@ module Phronomy
         config = @config
         fsm_id = @id
         parent_id = @parent_id
-        result_writer = @result_writer
 
-        Thread.new do
-          # Enable parallel tool dispatch inside this IO thread.
-          Thread.current[:phronomy_agent_parallel_tools] = true
-
-          begin
-            result = agent.send(:_invoke_impl,
-              input,
-              messages: messages,
-              thread_id: thread_id,
-              config: config)
-
-            if parent_id
-              # Let the caller write the result into the context BEFORE the
-              # parent FSMSession advances.  Thread::Queue provides the
-              # happens-before guarantee — no Mutex needed.
-              result_writer&.call(result)
-
-              Phronomy::EventLoop.instance.post(
-                Phronomy::Event.new(type: :child_completed, target_id: parent_id, payload: result)
-              )
-            end
+        Phronomy::Runtime.instance.spawn(name: "agent-fsm:#{fsm_id}") do
+          result = agent.send(:_invoke_impl,
+            input,
+            messages: messages,
+            thread_id: thread_id,
+            config: config)
 
+          if parent_id
+            # Result is delivered exclusively as the :child_completed payload.
+            # The parent Workflow task is the sole owner of WorkflowContext
+            # and applies the result after receiving the event.
             Phronomy::EventLoop.instance.post(
-              Phronomy::Event.new(type: :finished, target_id: fsm_id, payload: result)
+              Phronomy::Event.new(type: :child_completed, target_id: parent_id, payload: result)
             )
-          rescue => e
+          end
+
+          Phronomy::EventLoop.instance.post(
+            Phronomy::Event.new(type: :finished, target_id: fsm_id, payload: result)
+          )
+        rescue => e
+          if parent_id
             Phronomy::EventLoop.instance.post(
-              Phronomy::Event.new(type: :error, target_id: fsm_id, payload: e)
+              Phronomy::Event.new(type: :child_failed, target_id: parent_id, payload: e)
             )
           end
+
+          Phronomy::EventLoop.instance.post(
+            Phronomy::Event.new(type: :error, target_id: fsm_id, payload: e)
+          )
+
+          # Context caches are instance variables; no thread-local cleanup needed.
         end
       end
     end

data/lib/phronomy/agent/handoff.rb

@@ -22,6 +22,7 @@ module Phronomy
 
       # @param target_agent [Phronomy::Agent::Base] the agent to hand off to
       # @param description  [String, nil] overrides the auto-generated tool description
+      # @api public
       def initialize(target_agent:, description: nil)
         @target_agent = target_agent
         klass_name = target_agent.class.name&.split("::")&.last || "Agent"
@@ -33,6 +34,7 @@ module Phronomy
 
       # Builds an anonymous Phronomy::Tool::Base subclass for this handoff.
       # @return [Class<Phronomy::Tool::Base>]
+      # @api public
       def to_tool_class
         sentinel_value = sentinel
         tn = tool_name
@@ -46,6 +48,7 @@ module Phronomy
 
       # The sentinel string embedded in the tool result.
       # @return [String]
+      # @api public
       def sentinel
         "#{SENTINEL_PREFIX}:#{target_agent.class.name}:#{@uuid}"
       end