phronomy 0.14.0 → 0.15.0

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

@@ -8,11 +8,11 @@ module Phronomy
         #
         # Additional DSL over RubyLLM::Tool:
         #   - tool_name         : explicit function name exposed to the LLM (overrides auto-conversion)
-        #   - scope             : access-scope metadata (:read_only, :write, etc.)
         #   - on_error          : error-handling policy (:raise or :return_empty)
         #   - on_schema_error   : behavior when LLM passes schema-violating arguments
         #                         :return_error (default), :raise, or :coerce
-        #   - requires_approval : require human approval before execution
+        #   - requires_approval : Boolean/callable Tool-side approval default
+        #   - approval_facts    : callable exposing semantic facts to Agent policy
         #   - param :name, enum: [...] : restrict allowed values in the JSON Schema
         #
         # @example
@@ -21,7 +21,6 @@ module Phronomy
         #     description "Search the internal knowledge base"
         #     param :query,  type: :string, desc: "Search query"
         #     param :lang,   type: :string, desc: "Language", required: false, enum: %w[en ja fr]
-        #     scope :read_only
         #     on_error :return_empty
         #
         #     def execute(query:, lang: "en")
@@ -91,17 +90,6 @@ module Phronomy
 
             public
 
-            # Sets the access scope for this tool (metadata; enforcement is the responsibility of
-            # 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
-            def scope(value = nil)
-              return @scope if value.nil?
-
-              @scope = value
-            end
-
             # Sets or reads the execution mode for this tool.
             #
             # Execution mode is the concurrency contract declaration for the tool.
@@ -174,14 +162,41 @@ module Phronomy
               @on_schema_error = behavior
             end
 
-            # Configures whether human approval is required before executing this tool.
-            # @param value [Boolean]
+            # Configures the Tool-side default for approval. A callable receives
+            # ApprovalEvaluationRequest and must return true or false. It is
+            # evaluated on the Runtime authorization pool, not in Tool#call.
+            # @param value [Boolean, #call]
             # @api public
-            # mutant:disable - neutral failure: unparser round-trip produces different source
-            def requires_approval(value = nil)
-              return @requires_approval || false if value.nil?
+            def requires_approval(value = :__unset__, &block)
+              if block
+                unless value == :__unset__
+                  raise ArgumentError, "pass either a value or a block to requires_approval"
+                end
+                @requires_approval = block
+              elsif value == :__unset__
+                return @requires_approval if instance_variable_defined?(:@requires_approval)
+                return superclass.requires_approval if superclass.respond_to?(:requires_approval)
 
-              @requires_approval = value
+                false
+              else
+                unless value == true || value == false || value.respond_to?(:call)
+                  raise ArgumentError, "requires_approval must be true, false, or callable"
+                end
+                @requires_approval = value
+              end
+            end
+
+            # Registers a Tool-specific semantic fact extractor for authorization.
+            # The block receives validated immutable arguments and read-only context.
+            # @api public
+            def approval_facts(&block)
+              if block
+                @approval_facts = block
+              elsif instance_variable_defined?(:@approval_facts)
+                @approval_facts
+              elsif superclass.respond_to?(:approval_facts)
+                superclass.approval_facts
+              end
             end
 
             # Marks one or more parameter names as sensitive so their values are
@@ -211,49 +226,6 @@ module Phronomy
 
               @max_result_size = value
             end
-
-            # Registers a retry policy for one or more exception classes.
-            #
-            # When the tool raises one of the listed exception classes, it will be
-            # retried up to +times+ times with the specified wait strategy.
-            # Multiple policies can be registered and are evaluated in order.
-            #
-            # 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)
-            # @param wait   [Symbol, Numeric] :exponential, :linear, or a fixed Float
-            # @param base   [Float]   base wait time in seconds (default: 1.0)
-            #
-            # @example
-            #   retry_on Phronomy::ToolError, times: 3, wait: :exponential, base: 1.0
-            #   retry_on Net::ReadTimeout, times: 2, wait: 0.5
-            # @api public
-            def retry_on(*exception_classes, times: 1, wait: 0, base: 1.0)
-              @retry_policies ||= []
-              @retry_policies << {exceptions: exception_classes, times: times, wait: wait, base: base}
-            end
-
-            # Returns all retry policies registered on this tool class.
-            # @return [Array<Hash>]
-            # @api public
-            # mutant:disable - neutral failure: unparser round-trip produces different source
-            def retry_policies
-              @retry_policies || []
-            end
-
-            # Injectable sleep callable for testing.
-            # Defaults to Kernel#sleep.
-            # @return [#call]
-            # @api private
-            # mutant:disable - neutral failure: unparser round-trip produces different source
-            def _sleep_proc
-              @_sleep_proc || method(:sleep)
-            end
-
-            # Overrides the sleep callable used between retries.
-            # @param proc [#call]
-            attr_writer :_sleep_proc
           end
 
           # Returns the function name exposed to the LLM.
@@ -315,15 +287,15 @@ module Phronomy
             schema
           end
 
-          # Overrides RubyLLM::Tool#call to apply schema validation, the retry policy,
+          # Overrides RubyLLM::Tool#call to apply schema validation,
           # the on_error policy, and wrap errors as ToolError.
           #
           # Execution order:
           #   1. Early cancellation check (kwarg token takes precedence over thread-local).
           #   2. Schema validation (type + enum checks).
           #   3. Inject +cancellation_token:+ into args when +execute+ opts in.
-          #   4. Call super(validated_args) inside a retry loop.
-          #   5. On persistent failure, apply on_error policy.
+          #   4. Call super(validated_args) exactly once.
+          #   5. On failure, apply on_error policy.
           #
           # @param args               [Hash]
           # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil] optional; takes precedence over the thread-local token
@@ -343,7 +315,7 @@ module Phronomy
               end
             end
             validated_args = validated_args.merge(cancellation_token: ct) if ct && execute_accepts_cancellation_token?
-            result = with_tool_retry { super(validated_args) }
+            result = super(validated_args)
             truncate_result_if_needed(result)
           rescue Phronomy::ToolError
             raise
@@ -397,6 +369,18 @@ module Phronomy
             self.class.requires_approval
           end
 
+          # Origin metadata consumed by ToolInvocation authorization policy.
+          # @api public
+          def tool_origin
+            :local
+          end
+
+          # Display-safe transport/origin metadata for approval requests.
+          # @api public
+          def approval_metadata
+            {}
+          end
+
           # Override this method to implement the tool's logic.
           #
           # The method receives the declared {.param} fields as keyword arguments.
@@ -460,58 +444,6 @@ module Phronomy
             end
           end
 
-          # Executes the given block inside a retry loop driven by the class-level
-          # retry_policies. Each policy matches by exception class; the first matching
-          # policy governs the wait and retry count. Raises immediately when no policy
-          # covers the exception or when all retries are exhausted.
-          # mutant:disable - genuine equivalent mutations:
-          #   1. `if policies.empty?; return yield; end` early-return variants (nil, false, block
-          #      removal): behavior is identical because when policies is empty, yield is still
-          #      called inside begin/rescue, any exception is re-raised (policy=nil, condition
-          #      false), and successful returns propagate the same value either way.
-          #   2. `p[:exceptions].any?` vs `p.fetch(:exceptions).any?`: :exceptions key is always
-          #      present (set unconditionally by .retry_on), so fetch/[] are equivalent.
-          #   3. `policy[:times]`, `policy[:wait]`, `policy[:base]` vs `.fetch(...)`: same reason
-          #      as #2 — all keys are always set by .retry_on.
-          def with_tool_retry
-            policies = self.class.retry_policies
-            return yield if policies.empty?
-
-            attempt = 0
-            begin
-              yield
-            rescue => e
-              policy = policies.find { |p| p[:exceptions].any? { |ex| e.is_a?(ex) } }
-              if policy && attempt < policy[:times]
-                wait = compute_retry_wait(policy[:wait], policy[:base], attempt)
-                self.class._sleep_proc.call(wait) if wait > 0
-                attempt += 1
-                retry
-              end
-              raise
-            end
-          end
-
-          # Computes the wait duration for a given strategy, base, and attempt index.
-          #
-          # @param strategy [Symbol, Numeric] :exponential, :linear, or a fixed Numeric
-          # @param base     [Float]           base wait time in seconds
-          # @param attempt  [Integer]         zero-based attempt index
-          # @return [Float]
-          # @api public
-          def compute_retry_wait(strategy, base, attempt)
-            case strategy
-            when :exponential
-              (2**attempt) * base
-            when :linear
-              (attempt + 1) * base
-            when Numeric
-              strategy.to_f
-            else
-              base.to_f
-            end
-          end
-
           # Validates args against declared parameter types and enum constraints.
           # When on_schema_error is :coerce, attempts type coercion first.
           #

data/lib/phronomy/agent/llm_operation_result.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    # Immutable carrier for one LLM adapter operation outcome.
+    #
+    # Worker/timer threads create this value without mutating AgentInvocation.
+    # AgentInvocationSessionBuilder posts it as :llm_completed or :llm_failed,
+    # and AgentInvocation applies it on the EventLoop thread.
+    #
+    # @api private
+    class LLMOperationResult
+      attr_reader :response, :error, :streaming
+
+      def initialize(response: nil, error: nil, streaming: false)
+        @response = response
+        @error = error
+        @streaming = streaming
+        freeze
+      end
+    end
+  end
+end

data/lib/phronomy/agent/phase_machine_builder.rb

@@ -4,186 +4,124 @@ require "state_machines"
 
 module Phronomy
   module Agent
-    # Builds the state_machines-backed PhaseTracker class for Agent invocations.
+    # Compiles AgentInvocation phase topology.
     #
-    # This is the Agent counterpart to Workflow::PhaseMachineBuilder.
-    # Unlike the Workflow version (which builds a dynamic graph from user-defined
-    # DSL), this always generates the same fixed graph representing the
-    # Agent invoke execution phases.
-    #
-    # The generated class holds a single +:phase+ state machine with:
-    #   - One automatic event (+:state_completed+) that FSMSession fires after
-    #     each entry action completes.
-    #   - Two external events (+:approve+, +:reject+) for HITL.
-    #   - after_transition callbacks for each state's entry actions.
-    #
-    # Guard methods (+input_passed?+, +tool_call_pending?+, etc.) are delegated
-    # to the +InvocationContext+ stored in +attr_accessor :context+.
+    # Async completion is represented by explicit FSM events. This builder does
+    # not await Tasks or register Task callbacks.
     #
     # @api private
     class PhaseMachineBuilder
-      # @param entry_actions   [Hash{Symbol => Array<#call>}]
-      # @param action_timeouts [Hash{Symbol => Numeric}]
-      # @api private
-      def initialize(entry_actions: {}, action_timeouts: {})
+      TOOL_EVENTS = %i[
+        tool_authorized
+        tool_approval_required
+        tool_completed
+        tool_failed
+        tool_rejected
+        tool_cancelled
+      ].freeze
+
+      def initialize(entry_actions: {})
         @entry_actions = entry_actions
-        @action_timeouts = action_timeouts
       end
 
-      # Builds and returns the PhaseTracker class.
-      # @return [Class]
-      # @api private
       def build
-        entry_acts = @entry_actions
-        act_timeouts = @action_timeouts
-        build_cb = method(:build_entry_callback)
+        entry_actions = @entry_actions
+        callback_builder = method(:build_entry_callback)
 
         Class.new do
-          # state_machines requires a class-level state machine definition.
+          attr_accessor :context, :current_event
+
           state_machine :phase, initial: :idle do
-            # ----------------------------------------------------------------
-            # State declarations
-            # ----------------------------------------------------------------
             state :idle
             state :filtering_input
             state :building_context
             state :calling_llm
-            state :executing_tool
-            state :awaiting_approval  # wait_state: external event required
+            state :starting_tools
+            state :evaluating_tools
+            state :waiting_for_tools
+            state :dispatching_tools
+            state :recording_tool_results
+            state :suspended
             state :output_filtering
-            state :completed          # terminal
-            state :blocked            # terminal
+            state :completed
+            state :blocked
+            state :failed
 
-            # ----------------------------------------------------------------
-            # Automatic transitions (fired by FSMSession on state_completed)
-            # Guards are evaluated on the InvocationContext via #context.
-            # ----------------------------------------------------------------
             event :state_completed do
-              # idle → filtering_input (unconditional)
               transition idle: :filtering_input
 
-              # filtering_input → building_context | blocked
-              transition filtering_input: :building_context, if: ->(m) { m.context&.input_passed? }
-              transition filtering_input: :blocked, if: ->(m) { m.context&.input_blocked? }
+              transition filtering_input: :building_context,
+                if: ->(machine) { machine.context&.input_passed? }
+              transition filtering_input: :blocked,
+                if: ->(machine) { machine.context&.input_blocked? }
 
-              # building_context → calling_llm (unconditional)
               transition building_context: :calling_llm
+              transition starting_tools: :evaluating_tools
+
+              transition evaluating_tools: :failed,
+                if: ->(machine) { machine.context&.tool_batch_failed? }
+              transition evaluating_tools: :blocked,
+                if: ->(machine) { machine.context&.tool_batch_rejected? }
+              transition evaluating_tools: :recording_tool_results,
+                if: ->(machine) { machine.context&.tool_batch_completed? }
+              transition evaluating_tools: :suspended,
+                if: ->(machine) { machine.context&.approval_required? }
+              transition evaluating_tools: :dispatching_tools,
+                if: ->(machine) { machine.context&.ready_to_dispatch? }
+              transition evaluating_tools: :waiting_for_tools
+
+              transition dispatching_tools: :evaluating_tools
+              transition recording_tool_results: :calling_llm
+
+              transition output_filtering: :completed,
+                if: ->(machine) { machine.context&.output_passed? }
+              transition output_filtering: :blocked,
+                if: ->(machine) { machine.context&.output_blocked? }
+            end
 
-              # calling_llm → executing_tool | output_filtering
-              transition calling_llm: :executing_tool, if: ->(m) { m.context&.tool_call_pending? }
+            event :llm_completed do
+              transition calling_llm: :starting_tools,
+                if: ->(machine) { machine.context&.tool_call_pending? }
               transition calling_llm: :output_filtering
+            end
 
-              # executing_tool → awaiting_approval | calling_llm
-              transition executing_tool: :awaiting_approval, if: ->(m) { m.context&.approval_required? }
-              transition executing_tool: :calling_llm
-
-              # output_filtering → completed | blocked
-              transition output_filtering: :completed, if: ->(m) { m.context&.output_passed? }
-              transition output_filtering: :blocked, if: ->(m) { m.context&.output_blocked? }
+            event :llm_failed do
+              transition calling_llm: :failed
             end
 
-            # ----------------------------------------------------------------
-            # External events (human-in-the-loop)
-            # ----------------------------------------------------------------
-            event :approve do
-              transition awaiting_approval: :executing_tool
+            TOOL_EVENTS.each do |event_name|
+              event event_name do
+                transition waiting_for_tools: :evaluating_tools
+              end
             end
 
-            event :reject do
-              transition awaiting_approval: :blocked
+            event :resume do
+              transition suspended: :waiting_for_tools
             end
 
-            # ----------------------------------------------------------------
-            # Entry action after_transition callbacks
-            # Each state's callables are fired after entering that state.
-            # ----------------------------------------------------------------
-            entry_acts.each do |state_name, callables|
+            entry_actions.each do |state_name, callables|
               callables.each do |callable|
-                timeout_secs = act_timeouts[state_name]
-                cb = build_cb.call(callable, state_name, timeout_secs)
-                after_transition to: state_name, do: cb
+                after_transition(
+                  to: state_name,
+                  do: callback_builder.call(callable, state_name)
+                )
               end
             end
           end
-
-          # Holds the InvocationContext so guard lambdas can access it.
-          attr_accessor :context
-
-          # async_pending flag: set when an entry action returns a Task.
-          attr_accessor :async_pending
-
-          # FSM session id — set by FSMSession so async task spawns know the
-          # target_id for EventLoop events.
-          attr_accessor :session_id
-          attr_accessor :event_loop, :timer_queue_provider
-
-          def initialize
-            super
-            @context = nil
-            @async_pending = false
-            @session_id = nil
-          end
         end
       end
 
       private
 
-      # Returns a proc suitable for use as an after_transition callback.
-      # @api private
-      def build_entry_callback(callable, state_name, timeout_secs)
-        handle = method(:handle_entry_action_result)
+      def build_entry_callback(callable, state_name)
         ->(machine) {
           result = callable.call(machine.context)
-          handle.call(machine, result, state_name, timeout_secs)
-        }
-      end
-
-      # Dispatches the return value of an entry action.
-      # - Task    → async: set async_pending and spawn a background task
-      # - context → sync:  update machine.context
-      # @api private
-      def handle_entry_action_result(machine, result, state_name, timeout_secs)
-        if result.is_a?(Phronomy::Task)
-          dispatch_task(machine, result, state_name, timeout_secs)
-        elsif result.respond_to?(:set_graph_metadata)
-          machine.context = result
-        end
-      end
-
-      # Marks the machine async-pending and spawns a Task to await the result.
-      # @api private
-      def dispatch_task(machine, result, state_name, timeout_secs)
-        machine.async_pending = true
-        session_id = machine.session_id
-        if timeout_secs
-          machine.timer_queue_provider.call.schedule(seconds: timeout_secs) do
-            next if result.done?
-
-            machine.event_loop.post(
-              Phronomy::Event.new(
-                type: :error,
-                target_id: Phronomy::EventLoop::SYSTEM_CHANNEL_ID,
-                payload: {session_id: session_id, result: Phronomy::ActionTimeoutError.new(
-                  "Action in state #{state_name.inspect} timed out after #{timeout_secs}s"
-                )}
-              )
-            )
+          if result.is_a?(Phronomy::Task)
+            raise Phronomy::InvalidAsyncEntryActionError,
+              "Agent entry action for #{state_name.inspect} returned Phronomy::Task"
           end
-        end
-        result.on_complete do |task_result, error|
-          if error
-            machine.event_loop.post(
-              Phronomy::Event.new(type: :error, target_id: Phronomy::EventLoop::SYSTEM_CHANNEL_ID, payload: {session_id: session_id, result: error})
-            )
-            next
-          end
-          ev = if task_result.respond_to?(:set_graph_metadata)
-            Phronomy::Event.new(type: :action_completed, target_id: session_id, payload: task_result)
-          else
-            Phronomy::Event.new(type: :state_completed, target_id: session_id, payload: nil)
-          end
-          machine.event_loop.post(ev)
-        end
+          machine.context = result if result.respond_to?(:set_graph_metadata)
+        }
       end
     end
   end

data/lib/phronomy/agent/tool_approval_request.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "time"
+
+module Phronomy
+  module Agent
+    # Application-facing notification for one suspended ToolCall batch.
+    #
+    # The request contains display-safe values only. Internal policy input is
+    # represented by {ApprovalEvaluationRequest} and is deliberately separate.
+    #
+    # @api public
+    class ToolApprovalRequest
+      # One ToolInvocation included in a batch approval request.
+      # @api public
+      class Item
+        attr_reader :tool_invocation_id,
+          :tool_call_id,
+          :tool_name,
+          :arguments,
+          :facts,
+          :reason,
+          :origin,
+          :metadata
+
+        def initialize(
+          tool_invocation_id:,
+          tool_call_id:,
+          tool_name:,
+          arguments:,
+          facts:,
+          reason:,
+          origin:,
+          metadata:
+        )
+          @tool_invocation_id = tool_invocation_id.to_s.freeze
+          @tool_call_id = tool_call_id&.to_s&.freeze
+          @tool_name = tool_name.to_s.freeze
+          @arguments = immutable_copy(arguments)
+          @facts = immutable_copy(facts)
+          @reason = reason&.to_s&.freeze
+          @origin = origin.to_sym
+          @metadata = immutable_copy(metadata)
+          freeze
+        end
+
+        def to_h
+          {
+            tool_invocation_id: @tool_invocation_id,
+            tool_call_id: @tool_call_id,
+            tool_name: @tool_name,
+            arguments: @arguments,
+            facts: @facts,
+            reason: @reason,
+            origin: @origin,
+            metadata: @metadata
+          }
+        end
+
+        private
+
+        def immutable_copy(value)
+          case value
+          when Hash
+            value.each_with_object({}) { |(k, v), h| h[immutable_copy(k)] = immutable_copy(v) }.freeze
+          when Array
+            value.map { |v| immutable_copy(v) }.freeze
+          when String
+            value.dup.freeze
+          else
+            value
+          end
+        end
+      end
+
+      attr_reader :id, :agent_invocation_id, :items, :created_at
+
+      def self.build(agent_invocation)
+        pending = agent_invocation.tool_invocations.select(&:awaiting_approval?)
+        new(
+          agent_invocation_id: agent_invocation.id,
+          items: pending.map { |invocation| build_item(invocation) }
+        )
+      end
+
+      def self.build_item(invocation)
+        Item.new(
+          tool_invocation_id: invocation.id,
+          tool_call_id: invocation.tool_call_id,
+          tool_name: invocation.tool_name,
+          arguments: invocation.display_arguments,
+          facts: invocation.display_facts,
+          reason: invocation.authorization_reason,
+          origin: invocation.origin,
+          metadata: invocation.metadata
+        )
+      end
+      private_class_method :build_item
+
+      def initialize(agent_invocation_id:, items:, id: SecureRandom.uuid, created_at: Time.now.utc)
+        raise ArgumentError, "ToolApprovalRequest requires at least one item" if items.empty?
+
+        @id = id.to_s.freeze
+        @agent_invocation_id = agent_invocation_id.to_s.freeze
+        @items = items.dup.freeze
+        @created_at = created_at
+        freeze
+      end
+
+      def to_h
+        {
+          id: @id,
+          agent_invocation_id: @agent_invocation_id,
+          items: @items.map(&:to_h),
+          created_at: @created_at.iso8601
+        }
+      end
+    end
+  end
+end

data/lib/phronomy/agent/tool_call_intercepted.rb

@@ -2,24 +2,20 @@
 
 module Phronomy
   module Agent
-    # Raised inside the on_tool_call hook registered by InvocationSession
-    # to intercept every tool call before RubyLLM executes it.
-    #
-    # Catching this exception in calling_llm_action lets the Agent FSM
-    # route through :executing_tool (and possibly :awaiting_approval) rather
-    # than executing the tool inside RubyLLM's internal loop.
-    #
-    # This class is intentionally NOT part of the public API.
+    # Raised by the Agent-owned RubyLLM ToolCall interceptor before execution.
     # @api private
     class ToolCallIntercepted < StandardError
-      # @return [Object] the RubyLLM tool_call object (responds to #name, #arguments, #id)
-      attr_reader :tool_call
+      attr_reader :tool_calls
 
-      # @param tool_call [Object] the RubyLLM tool_call object
-      # @api private
-      def initialize(tool_call)
-        super("Tool call intercepted: #{tool_call.name}")
-        @tool_call = tool_call
+      def initialize(tool_calls)
+        @tool_calls = Array(tool_calls).freeze
+        names = @tool_calls.map(&:name).join(", ")
+        super("Tool call intercepted: #{names}")
+      end
+
+      # Convenience accessor for callers that only support one ToolCall.
+      def tool_call
+        @tool_calls.first
       end
     end
   end