phronomy 0.10.0 → 0.11.1

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

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    module Concerns
+      # Adds input, output, and tool-result filter support to an agent.
+      #
+      # Filters transform (or block) values at three call sites:
+      #   - *input*       — the raw user input string, before the LLM is called
+      #   - *output*      — the final LLM output string, before it is returned
+      #   - *tool result* — the return value of each tool call
+      #
+      # Each filter in the chain receives the value returned by the previous one.
+      # A {Phronomy::FilterBlockError} raised inside any filter propagates to the
+      # caller.
+      #
+      # @api private
+      module Filterable
+        def self.included(base)
+          base.extend(ClassMethods)
+        end
+
+        # Class-level DSL mixed into the including agent class.
+        module ClassMethods
+          # Registers a filter applied to every invocation's user input.
+          # Accepts either a {Phronomy::Filter::Base} instance or a subclass;
+          # when a class is given it is instantiated with +.new+.
+          # @param filter [Phronomy::Filter::Base, Class<Phronomy::Filter::Base>]
+          # @return [void]
+          # @api public
+          def input_filter(filter)
+            @_class_input_filters ||= []
+            @_class_input_filters << _resolve_filter(filter)
+          end
+
+          # Registers a filter applied to every invocation's final LLM output.
+          # Accepts either a {Phronomy::Filter::Base} instance or a subclass;
+          # when a class is given it is instantiated with +.new+.
+          # @param filter [Phronomy::Filter::Base, Class<Phronomy::Filter::Base>]
+          # @return [void]
+          # @api public
+          def output_filter(filter)
+            @_class_output_filters ||= []
+            @_class_output_filters << _resolve_filter(filter)
+          end
+
+          # Registers a filter applied to every tool result for all tools.
+          # Accepts either a {Phronomy::Filter::Base} instance or a subclass;
+          # when a class is given it is instantiated with +.new+.
+          # @param filter [Phronomy::Filter::Base, Class<Phronomy::Filter::Base>]
+          # @return [void]
+          # @api public
+          def tool_result_filter(filter)
+            @_class_tool_result_filters ||= []
+            @_class_tool_result_filters << _resolve_filter(filter)
+          end
+
+          # @return [Array<Phronomy::Filter::Base>]
+          # @api private
+          def _class_input_filters
+            @_class_input_filters || []
+          end
+
+          # @return [Array<Phronomy::Filter::Base>]
+          # @api private
+          def _class_output_filters
+            @_class_output_filters || []
+          end
+
+          # @return [Array<Phronomy::Filter::Base>]
+          # @api private
+          def _class_tool_result_filters
+            @_class_tool_result_filters || []
+          end
+
+          private
+
+          # Coerce +filter+ to an instance: if a Class is passed, call +.new+;
+          # otherwise return the object as-is.
+          # @param filter [Phronomy::Filter::Base, Class<Phronomy::Filter::Base>]
+          # @return [Phronomy::Filter::Base]
+          # @api private
+          def _resolve_filter(filter)
+            filter.is_a?(Class) ? filter.new : filter
+          end
+        end
+
+        # Registers an input filter on this instance.
+        # Accepts either a {Phronomy::Filter::Base} instance or a subclass;
+        # when a class is given it is instantiated with +.new+.
+        # Runs in addition to any class-level input filters.
+        # @param filter [Phronomy::Filter::Base, Class<Phronomy::Filter::Base>]
+        # @return [self]
+        # @api public
+        def add_input_filter(filter)
+          @_instance_input_filters ||= []
+          @_instance_input_filters << _resolve_filter(filter)
+          self
+        end
+
+        # Registers an output filter on this instance.
+        # Accepts either a {Phronomy::Filter::Base} instance or a subclass;
+        # when a class is given it is instantiated with +.new+.
+        # Runs in addition to any class-level output filters.
+        # @param filter [Phronomy::Filter::Base, Class<Phronomy::Filter::Base>]
+        # @return [self]
+        # @api public
+        def add_output_filter(filter)
+          @_instance_output_filters ||= []
+          @_instance_output_filters << _resolve_filter(filter)
+          self
+        end
+
+        # Registers a tool result filter on this instance.
+        #
+        # When called with two arguments, the filter is scoped to the given tool
+        # class only.  When called with one argument, it applies to all tools.
+        # Accepts either a {Phronomy::Filter::Base} instance or a subclass;
+        # when a class is given it is instantiated with +.new+.
+        #
+        # @overload add_tool_result_filter(filter)
+        #   @param filter [Phronomy::Filter::Base, Class<Phronomy::Filter::Base>] applied to every tool
+        # @overload add_tool_result_filter(tool_class, filter)
+        #   @param tool_class [Class] scope the filter to this tool
+        #   @param filter [Phronomy::Filter::Base, Class<Phronomy::Filter::Base>]
+        # @return [self]
+        # @api public
+        def add_tool_result_filter(tool_class_or_filter, filter = nil)
+          if filter.nil?
+            # Single-argument form: apply to all tools.
+            @_instance_tool_result_filters ||= []
+            @_instance_tool_result_filters << _resolve_filter(tool_class_or_filter)
+          else
+            # Two-argument form: scoped to one tool class.
+            @_scoped_tool_result_filters ||= {}
+            (@_scoped_tool_result_filters[tool_class_or_filter] ||= []) << _resolve_filter(filter)
+          end
+          self
+        end
+
+        private
+
+        # Run input filters (class-level then instance-level).
+        # @param input [String, Hash] the raw user input
+        # @return [String, Hash] the (possibly transformed) input
+        # @api private
+        def run_input_filters!(input)
+          class_filters = self.class._class_input_filters
+          inst_filters = @_instance_input_filters || []
+          (class_filters + inst_filters).inject(input) { |val, f| f.call(val) }
+        end
+
+        # Run output filters (class-level then instance-level).
+        # @param output [String] the LLM output
+        # @return [String] the (possibly transformed) output
+        # @api private
+        def run_output_filters!(output)
+          class_filters = self.class._class_output_filters
+          inst_filters = @_instance_output_filters || []
+          (class_filters + inst_filters).inject(output) { |val, f| f.call(val) }
+        end
+
+        # Collect all tool-result filters (global + scoped) for a given tool class.
+        # @param tool_class [Class]
+        # @return [Array<Phronomy::Filter::Base>]
+        # @api private
+        def _tool_result_filters_for(tool_class)
+          global = self.class._class_tool_result_filters + (@_instance_tool_result_filters || [])
+          scoped = (@_scoped_tool_result_filters || {})[tool_class] || []
+          global + scoped
+        end
+
+        # Coerce +filter+ to an instance: if a Class is passed, call +.new+;
+        # otherwise return the object as-is.
+        # @param filter [Phronomy::Filter::Base, Class<Phronomy::Filter::Base>]
+        # @return [Phronomy::Filter::Base]
+        # @api private
+        def _resolve_filter(filter)
+          filter.is_a?(Class) ? filter.new : filter
+        end
+      end
+    end
+  end
+end

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

@@ -6,7 +6,7 @@ module Phronomy
       # Adds configurable retry behaviour to an agent.
       #
       # Included in {Phronomy::Agent::Base}. The retry loop wraps the full
-      # #invoke_once call; {Phronomy::GuardrailError} is never retried.
+      # #invoke_once call; {Phronomy::FilterBlockError} is never retried.
       # @api private
       module Retryable
         def self.included(base)
@@ -16,7 +16,7 @@ module Phronomy
         # Class-level DSL methods mixed into the including agent class.
         module ClassMethods
           # Configures a retry policy that wraps the full #invoke call.
-          # GuardrailError is never retried regardless of this setting.
+          # FilterBlockError is never retried regardless of this setting.
           #
           # @param times [Integer] maximum retry attempts (default: 0)
           # @param wait  [Symbol, Numeric] :exponential, :linear, or a fixed Float
@@ -35,7 +35,11 @@ module Phronomy
           # @return [Hash, nil]
           attr_reader :_retry_policy
 
-          # Injectable sleep callable for testing (shared with Tool::Base pattern).
+          # Injectable sleep callable for testing.
+          # In the EventLoop-driven invoke path, actual delay is handled by
+          # timer_queue (non-blocking); _sleep_proc is called only as an
+          # instrumentation hook.  The default is a no-op; tests override it
+          # with a spy lambda to record sleep durations.
           # @return [#call]
           # @api private
           def _sleep_proc
@@ -59,8 +63,8 @@ module Phronomy
           policy = self.class._retry_policy
           attempt = 0
           begin
-            invoke_once(input, messages: messages, thread_id: thread_id, config: config)
-          rescue Phronomy::GuardrailError
+            _invoke_via_fsm(input, messages: messages, thread_id: thread_id, config: config)
+          rescue Phronomy::FilterBlockError
             raise
           rescue Phronomy::CancellationError
             raise # Never retry after cancellation.

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

@@ -92,7 +92,7 @@ module Phronomy
             public
 
             # Sets the access scope for this tool (metadata; enforcement is the responsibility of
-            # the Workflow/Guardrail layer).
+            # the Workflow/Filter layer).
             # @param value [Symbol] e.g. :read_only, :write, :admin
             # @api public
             # mutant:disable - neutral failure: unparser round-trip produces different source
@@ -218,7 +218,7 @@ module Phronomy
             # retried up to +times+ times with the specified wait strategy.
             # Multiple policies can be registered and are evaluated in order.
             #
-            # GuardrailError is never retried regardless of this configuration.
+            # FilterBlockError is never retried regardless of this configuration.
             #
             # @param exception_classes [Array<Class>] exception classes to retry on
             # @param times  [Integer] maximum retry attempts (default: 1)

data/lib/phronomy/agent/invocation_context.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    # Holds the mutable state for a single Agent#invoke execution.
+    #
+    # An InvocationContext is created at the start of each invoke call and
+    # passed through every FSM state as the context object. It plays the same
+    # role as WorkflowContext does for Workflow executions.
+    #
+    # Fields:
+    #   input                  — the (possibly filter-transformed) user input
+    #   messages               — conversation history (Array of RubyLLM::Message)
+    #   chat                   — the RubyLLM::Chat object built during :building_context
+    #   output                 — the final LLM text response
+    #   usage                  — Phronomy::TokenUsage after completion
+    #   tool_call_pending      — whether the last LLM response contained a tool call
+    #   approval_required      — whether the pending tool requires human approval
+    #   input_blocked          — whether an input filter called block!
+    #   output_blocked         — whether an output filter called block!
+    #   block_error            — the FilterBlockError raised (for :blocked terminal)
+    #   pending_tool_call      — the intercepted tool_call object (name/arguments/id)
+    #   user_message_sent      — true after the first LLM call (continuation uses nil msg)
+    #   sync_approval_handler  — true when agent has an on_approval_required block
+    #   session_id             — FSM session id (set by set_graph_metadata)
+    #   phase                  — terminal FSM phase (set by set_graph_metadata)
+    #
+    # @api private
+    class InvocationContext
+      # @return [String, Hash] user input (may be transformed by input filters)
+      attr_accessor :input
+
+      # @return [Array] conversation history
+      attr_accessor :messages
+
+      # @return [Object, nil] RubyLLM::Chat instance
+      attr_accessor :chat
+
+      # @return [String, nil] final LLM output text
+      attr_accessor :output
+
+      # @return [Phronomy::TokenUsage, nil]
+      attr_accessor :usage
+
+      # @return [Boolean] true when calling_llm returned a tool call
+      attr_accessor :tool_call_pending
+
+      # @return [Boolean] true when the pending tool requires human approval
+      attr_accessor :approval_required
+
+      # @return [Boolean] true when an input filter called block!
+      attr_accessor :input_blocked
+
+      # @return [Boolean] true when an output filter called block!
+      attr_accessor :output_blocked
+
+      # @return [Phronomy::FilterBlockError, nil]
+      attr_accessor :block_error
+
+      # @return [Object, nil] intercepted RubyLLM tool_call (name/arguments/id)
+      attr_accessor :pending_tool_call
+
+      # @return [Boolean] true after the first LLM call (continuation passes nil msg)
+      attr_accessor :user_message_sent
+
+      # @return [Boolean] true when Agent.approve was called (signals executing_tool
+      #   to execute the pending tool rather than re-suspending)
+      attr_accessor :approved
+
+      # @return [Boolean] true when the pending tool call was rejected via
+      #   Agent.approve(session_id, approved: false)
+      attr_accessor :rejected
+
+      # @return [String, nil] FSM session id (set by set_graph_metadata)
+      attr_reader :session_id
+
+      # @return [Symbol, nil] terminal FSM phase (set by set_graph_metadata)
+      attr_reader :phase
+
+      # @return [Boolean] true when agent has a synchronous on_approval_required handler
+      attr_reader :sync_approval_handler
+
+      # @return [Phronomy::Agent::Base] the agent instance driving this invocation
+      attr_reader :agent
+
+      # @return [Hash] the config hash passed to invoke
+      attr_reader :config
+
+      # @return [String, nil] thread_id from config
+      attr_reader :thread_id
+
+      # @param agent    [Phronomy::Agent::Base]
+      # @param input    [String, Hash]
+      # @param messages [Array]
+      # @param config   [Hash]
+      # @api private
+      def initialize(agent:, input:, messages:, config:)
+        @agent = agent
+        @input = input
+        @messages = Array(messages)
+        @config = config
+        @thread_id = config[:thread_id]
+        @chat = nil
+        @output = nil
+        @usage = nil
+        @tool_call_pending = false
+        @approval_required = false
+        @input_blocked = false
+        @output_blocked = false
+        @block_error = nil
+        @pending_tool_call = nil
+        @user_message_sent = false
+        @approved = false
+        @rejected = false
+        @sync_approval_handler = !agent.instance_variable_get(:@approval_handler).nil?
+        @session_id = nil
+        @phase = nil
+      end
+
+      # Called by FSMSession#finish! and FSMSession#halt! to record the
+      # terminal/halted phase and the session id.
+      # Mirrors the WorkflowContext interface so FSMSession works with both.
+      # @param thread_id [String, nil]
+      # @param phase     [Symbol, nil]
+      # @return [void]
+      # @api private
+      def set_graph_metadata(thread_id: nil, phase: nil)
+        @session_id = thread_id if thread_id
+        @phase = phase
+      end
+
+      # Guard helpers used by PhaseMachineBuilder transitions.
+
+      # @return [Boolean]
+      # @api private
+      def input_passed?
+        !@input_blocked
+      end
+
+      # @return [Boolean]
+      # @api private
+      def input_blocked?
+        @input_blocked
+      end
+
+      # @return [Boolean]
+      # @api private
+      def output_passed?
+        !@output_blocked
+      end
+
+      # @return [Boolean]
+      # @api private
+      def output_blocked?
+        @output_blocked
+      end
+
+      # @return [Boolean]
+      # @api private
+      def tool_call_pending?
+        @tool_call_pending
+      end
+
+      # @return [Boolean]
+      # @api private
+      def approval_required?
+        @approval_required
+      end
+    end
+  end
+end