phronomy 0.6.0 → 0.7.1

data/lib/phronomy/tool/base.rb

@@ -33,44 +33,121 @@ module Phronomy
         # When omitted, RubyLLM's default conversion applies (e.g. WeatherTool → "weather").
         #
         # @param value [String, nil] the exact function name the LLM will see
+        # @api public
         def tool_name(value = nil)
           return @tool_name if value.nil?
 
           @tool_name = value.to_s
         end
 
-        # Extends RubyLLM::Tool.param with an optional +enum:+ keyword.
-        # The enum values are stored separately and injected into the JSON Schema
-        # produced by #params_schema.
+        # Extends RubyLLM::Tool.param with optional +enum:+ and +properties:+ keywords.
+        # - +enum:+       restricts allowed values; injected into the JSON Schema.
+        # - +properties:+ declares nested fields for :object type params.  Each
+        #   entry is a Hash mapping field name (Symbol) to a spec Hash with keys:
+        #   :type (Symbol, default :string), :required (Boolean, default false),
+        #   and optionally :properties (for further nesting).
         #
         # @param name [Symbol] parameter name
-        # @param enum [Array, nil] allowed values; when given, added as "enum" in JSON Schema
+        # @param enum [Array, nil] allowed values
+        # @param properties [Hash, nil] nested schema for :object params
         # @param options [Hash] forwarded to RubyLLM::Tool.param
-        def param(name, enum: nil, **options)
+        # @api public
+        def param(name, enum: nil, properties: nil, **options)
           super(name, **options)
           param_enums[name] = enum if enum
+          param_schemas[name] = normalize_nested_schema(properties) if properties
         end
 
         # Returns the enum constraints registered via .param.
         # @return [Hash{Symbol => Array}]
+        # @api public
         def param_enums
           @param_enums ||= {}
         end
 
+        # Returns nested schema definitions registered via .param(properties: ...).
+        # @return [Hash{Symbol => Hash}]
+        # @api public
+        def param_schemas
+          @param_schemas ||= {}
+        end
+
+        private
+
+        # Recursively normalises a properties hash so all keys are Symbols and
+        # each spec has a :type key.
+        def normalize_nested_schema(props)
+          props.transform_keys(&:to_sym).transform_values do |spec|
+            s = spec.transform_keys(&:to_sym)
+            s[:type] ||= :string
+            s[:properties] = normalize_nested_schema(s[:properties]) if s[:properties]
+            s
+          end
+        end
+
+        public
+
         # Sets the access scope for this tool (metadata; enforcement is the responsibility of
         # the Workflow/Guardrail layer).
         # @param value [Symbol] e.g. :read_only, :write, :admin
+        # @api public
         def scope(value = nil)
           return @scope if value.nil?
 
           @scope = value
         end
 
-        # Configures error-handling behavior.
-        # @param behavior [Symbol] :raise (default) or :return_empty
+        # Sets or reads the execution mode for this tool.
+        #
+        # Execution mode is the concurrency contract declaration for the tool.
+        # In Phronomy's non-preemptive, cooperative concurrency model it controls
+        # which runtime resource is used to dispatch the tool:
+        #
+        # | Mode | Dispatcher | Constraint |
+        # |------|-----------|------------|
+        # | +:cooperative+ | +Runtime.instance.spawn+ (scheduler task) | *Must not* block the scheduler thread; use only for in-memory computation |
+        # | +:blocking_io+ | {Phronomy::BlockingAdapterPool} (bounded thread pool) | **Default**. Safe for all blocking I/O (HTTP, DB, file) |
+        # | +:cpu_bound+ | Falls back to +:blocking_io+ + emits a warning | No dedicated process pool yet; use +:blocking_io+ explicitly to suppress the warning |
+        # | +:external_process+ | Falls back to +:blocking_io+ | No process manager yet |
+        #
+        # Tools that perform network calls, file I/O, or database queries should use
+        # +:blocking_io+ (the default).  Tools that only perform in-memory computation
+        # may declare +:cooperative+ for lower overhead.
+        #
+        # @param value [Symbol, nil] when nil, returns the current value
+        # @return [Symbol] the current execution mode (default :blocking_io)
+        # @api public
+        def execution_mode(value = nil)
+          return @execution_mode || :blocking_io if value.nil?
+
+          valid = %i[cooperative blocking_io cpu_bound external_process]
+          unless valid.include?(value)
+            raise ArgumentError, "execution_mode must be one of #{valid.inspect}, got #{value.inspect}"
+          end
+
+          @execution_mode = value
+        end
+
+        # Configures error-handling behavior when +execute+ raises an unexpected error.
+        #
+        # @param behavior [Symbol]
+        #   :raise        (default)  — re-raise as Phronomy::ToolError, stopping the agent.
+        #   :suppress                — suppress the error and return a descriptive string so
+        #                             the LLM can recover on the next turn.
+        #   :return_empty            — *deprecated* alias for +:suppress+; will be removed in a
+        #                             future major release.
+        # @api public
         def on_error(behavior = nil)
           return @on_error || :raise if behavior.nil?
 
+          if behavior == :return_empty
+            msg = "[Phronomy] on_error :return_empty is deprecated; use :suppress instead"
+            if Phronomy.configuration.logger
+              Phronomy.configuration.logger.warn(msg)
+            else
+              warn msg
+            end
+          end
           @on_error = behavior
         end
 
@@ -83,6 +160,7 @@ module Phronomy
         #   :raise                  — raise Phronomy::ToolError, stopping the agent loop.
         #   :coerce                 — attempt type coercion (e.g. "42" → 42 for :integer);
         #                             falls back to :return_error when coercion is not possible.
+        # @api public
         def on_schema_error(behavior = nil)
           return @on_schema_error || :return_error if behavior.nil?
 
@@ -91,12 +169,40 @@ module Phronomy
 
         # Configures whether human approval is required before executing this tool.
         # @param value [Boolean]
+        # @api public
         def requires_approval(value = nil)
           return @requires_approval || false if value.nil?
 
           @requires_approval = value
         end
 
+        # Marks one or more parameter names as sensitive so their values are
+        # replaced with +"[REDACTED]"+ in log and trace output.
+        #
+        # @param names [Array<Symbol>] parameter names to redact
+        # @return [Array<Symbol>] the full list of redacted param names
+        # @api public
+        def redact_params(*names)
+          if names.empty?
+            parent = superclass.respond_to?(:redact_params) ? superclass.redact_params : []
+            ((@redacted_params || []) + parent).uniq
+          else
+            @redacted_params = ((@redacted_params || []) + names.map(&:to_sym)).uniq
+          end
+        end
+
+        # Sets a per-tool maximum result size (in characters).
+        # Overrides the global +Phronomy.configuration.tool_result_max_size+ when set.
+        # Set to +nil+ to inherit the global limit.
+        #
+        # @param value [Integer, nil]
+        # @api public
+        def max_result_size(value = :__unset__)
+          return @max_result_size if value == :__unset__
+
+          @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
@@ -113,6 +219,7 @@ module Phronomy
         # @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}
@@ -120,6 +227,7 @@ module Phronomy
 
         # Returns all retry policies registered on this tool class.
         # @return [Array<Hash>]
+        # @api public
         def retry_policies
           @retry_policies || []
         end
@@ -127,6 +235,7 @@ module Phronomy
         # Injectable sleep callable for testing.
         # Defaults to Kernel#sleep.
         # @return [#call]
+        # @api private
         def _sleep_proc
           @_sleep_proc || method(:sleep)
         end
@@ -147,24 +256,37 @@ module Phronomy
       # Injects "enum" entries for any param declared with enum: [...].
       def params_schema
         schema = super
-        return schema if schema.nil? || self.class.param_enums.empty?
+        return schema if schema.nil?
 
-        enums = self.class.param_enums
         properties = schema.dig("properties") || schema.dig(:properties)
         return schema unless properties
 
-        enums.each do |param_name, values|
+        # Inject enum values for params declared with enum: [...].
+        unless self.class.param_enums.empty?
+          enums = self.class.param_enums
+          enums.each do |param_name, values|
+            key = properties.key?(param_name.to_s) ? param_name.to_s : param_name.to_sym
+            next unless properties[key]
+
+            param_type = properties[key]["type"]
+            properties[key]["enum"] = values.map do |v|
+              case param_type
+              when "integer" then v.is_a?(Integer) ? v : Integer(v.to_s)
+              when "number" then v.is_a?(Numeric) ? v : Float(v.to_s)
+              else v.to_s
+              end
+            end
+          end
+        end
+
+        # Inject nested properties for :object params (issue #162).
+        # Without this the LLM sees only { "type": "object" } with no field
+        # definitions, making it unable to populate nested object params.
+        self.class.param_schemas.each do |param_name, nested|
           key = properties.key?(param_name.to_s) ? param_name.to_s : param_name.to_sym
           next unless properties[key]
 
-          param_type = properties[key]["type"]
-          properties[key]["enum"] = values.map do |v|
-            case param_type
-            when "integer" then v.is_a?(Integer) ? v : Integer(v.to_s)
-            when "number" then v.is_a?(Numeric) ? v : Float(v.to_s)
-            else v.to_s
-            end
-          end
+          properties[key]["properties"] = nested_schema_to_json_schema(nested)
         end
 
         schema
@@ -174,10 +296,18 @@ module Phronomy
       # the on_error policy, and wrap errors as ToolError.
       #
       # Execution order:
-      #   1. Schema validation (type + enum checks).
-      #   2. Call super(validated_args) inside a retry loop.
-      #   3. On persistent failure, apply on_error policy.
-      def call(args)
+      #   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.
+      #
+      # @param args               [Hash]
+      # @param cancellation_token [Phronomy::CancellationToken, nil] optional; takes precedence over the thread-local token
+      # @api public
+      def call(args, cancellation_token: nil)
+        ct = cancellation_token
+        ct&.raise_if_cancelled!
         validated_args, schema_error = validate_and_coerce(args)
         if schema_error
           case self.class.on_schema_error
@@ -188,18 +318,46 @@ module Phronomy
             return "Schema validation failed: #{schema_error}"
           end
         end
-        with_tool_retry { super(validated_args) }
+        validated_args = validated_args.merge(cancellation_token: ct) if ct && execute_accepts_cancellation_token?
+        result = with_tool_retry { super(validated_args) }
+        truncate_result_if_needed(result)
       rescue Phronomy::ToolError
         raise
+      rescue Phronomy::CancellationError
+        raise
       rescue => e
         case self.class.on_error
-        when :return_empty
-          []
+        when :return_empty, :suppress
+          msg = "[Phronomy] Tool #{self.class.name} suppressed error: #{e.class}: #{e.message}"
+          if Phronomy.configuration.logger
+            Phronomy.configuration.logger.warn(msg)
+          else
+            warn msg
+          end
+          "Tool error suppressed: #{e.message}"
         else
           raise Phronomy::ToolError, "#{self.class.name} execution failed: #{e.message}"
         end
       end
 
+      # Invokes this tool asynchronously and returns a {Phronomy::Task}.
+      #
+      # Routing is governed by the class-level {.execution_mode} setting.
+      # Delegates to {Phronomy::ToolExecutor.call_async} which is the single
+      # place in the framework that applies the execution-mode routing rules.
+      #
+      # @param args               [Hash]
+      # @param cancellation_token [Phronomy::CancellationToken, nil]
+      # @return [#await]
+      # @api public
+      def call_async(args, cancellation_token: nil)
+        Phronomy::ToolExecutor.call_async(
+          tool: self,
+          args: args,
+          cancellation_token: cancellation_token
+        )
+      end
+
       # Instance method accessor — delegates to the class-level flag.
       def requires_approval
         self.class.requires_approval
@@ -226,12 +384,52 @@ module Phronomy
       #       WeatherService.fetch(location).to_s
       #     end
       #   end
+      # @api public
       def execute(**_args)
         raise NotImplementedError, "#{self.class}#execute is not implemented"
       end
 
       private
 
+      # Returns true when the #execute method declares a +cancellation_token:+
+      # keyword parameter, indicating it opts into cooperative cancellation.
+      def execute_accepts_cancellation_token?
+        method(:execute).parameters.any? do |type, name|
+          name == :cancellation_token && %i[key keyreq].include?(type)
+        end
+      end
+
+      # Truncates the result string when it exceeds the configured maximum size.
+      # Uses the per-tool limit first, then the global configuration limit.
+      # Returns the original result when no limit is configured.
+      def truncate_result_if_needed(result)
+        max = self.class.max_result_size || Phronomy.configuration.tool_result_max_size
+        return result unless max && result.respond_to?(:length) && result.length > max
+
+        msg = "[Phronomy] Tool #{self.class.name} result truncated " \
+              "(#{result.length} chars > #{max} limit)"
+        if Phronomy.configuration.logger
+          Phronomy.configuration.logger.warn(msg)
+        else
+          warn msg
+        end
+        "#{result[0, max]}...[truncated]"
+      end
+
+      # Returns a copy of +args+ with redacted parameter values replaced by
+      # +"[REDACTED]"+.  Used for logging and tracing.
+      # @param args [Hash]
+      # @return [Hash]
+      # @api private
+      def redacted_args(args)
+        redacted = self.class.redact_params
+        return args if redacted.empty?
+
+        args.each_with_object({}) do |(k, v), h|
+          h[k] = redacted.include?(k.to_sym) ? "[REDACTED]" : v
+        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
@@ -261,6 +459,7 @@ module Phronomy
       # @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
@@ -279,6 +478,7 @@ module Phronomy
       #
       # @param args [Hash] raw args passed to #call (string or symbol keys)
       # @return [Array(Hash, String|nil)] [possibly_coerced_args, error_message_or_nil]
+      # @api public
       def validate_and_coerce(args)
         return [args, nil] if self.class.parameters.empty?
 
@@ -304,6 +504,15 @@ module Phronomy
             return [nil, error] if error
           end
 
+          # Recursively validate nested object properties when declared.
+          if param.type.to_sym == :object
+            nested_schema = self.class.param_schemas[name]
+            if nested_schema
+              error = validate_nested_object(value, nested_schema, name.to_s)
+              return [nil, error] if error
+            end
+          end
+
           enum_vals = self.class.param_enums[name]
           if enum_vals && !enum_vals.map(&:to_s).include?(value.to_s)
             return [nil, "parameter '#{name}' must be one of: #{enum_vals.join(", ")} (got: #{value.inspect})"]
@@ -312,9 +521,69 @@ module Phronomy
           result[name] = value
         end
 
-        # Merge in any extra keys not covered by declared parameters (pass-through).
-        extra = normalized.reject { |k, _| self.class.parameters.key?(k) }
-        [result.merge(extra), nil]
+        # Reject any keys not covered by declared parameters to prevent silent
+        # parameter injection (e.g. via prompt injection).
+        extra = normalized.keys - self.class.parameters.keys
+        unless extra.empty?
+          return [nil, "unknown parameter(s): #{extra.inspect}"]
+        end
+
+        [result, nil]
+      end
+
+      # Converts the internal normalized nested schema (from param_schemas) to
+      # a JSON Schema +properties+ hash suitable for inclusion in the LLM tool
+      # definition (issue #162).
+      #
+      # @param nested [Hash{Symbol=>Hash}] normalized schema from param_schemas
+      # @return [Hash{String=>Hash}] JSON Schema properties
+      # @api public
+      def nested_schema_to_json_schema(nested)
+        nested.each_with_object({}) do |(prop_name, spec), acc|
+          entry = {"type" => spec[:type].to_s}
+          entry["description"] = spec[:desc] if spec[:desc]
+          entry["enum"] = spec[:enum] if spec[:enum]
+          entry["properties"] = nested_schema_to_json_schema(spec[:properties]) if spec[:properties]
+          acc[prop_name.to_s] = entry
+        end
+      end
+
+      # Recursively validates +value+ (a Hash) against a +properties+ schema.
+      # Returns an error message string or nil.
+      #
+      # @param value      [Hash]            the object value to validate
+      # @param properties [Hash{Symbol=>Hash}] nested schema from param_schemas
+      # @param path       [String]          dot-separated field path for error messages
+      # @api public
+      def validate_nested_object(value, properties, path)
+        return "field '#{path}' must be an object (Hash)" unless value.is_a?(Hash)
+
+        normalized = value.transform_keys(&:to_sym)
+
+        # Reject extra keys not declared in the schema (issue #166).
+        extra = normalized.keys - properties.keys
+        unless extra.empty?
+          return "nested field '#{path}' contains undeclared key(s): #{extra.inspect}"
+        end
+
+        properties.each do |fname, spec|
+          field_path = "#{path}.#{fname}"
+          field_value = normalized[fname]
+
+          if field_value.nil?
+            return "nested required field '#{field_path}' is missing" if spec[:required]
+            next
+          end
+
+          error = type_error(field_value, spec[:type])
+          return "nested field '#{field_path}': #{error}" if error
+
+          next unless spec[:type].to_sym == :object && spec[:properties]
+
+          error = validate_nested_object(field_value, spec[:properties], field_path)
+          return error if error
+        end
+        nil
       end
 
       # Returns a type-error message string if +value+ does not match +declared_type+,
@@ -322,6 +591,7 @@ module Phronomy
       #
       # @param value         [Object]
       # @param declared_type [Symbol, String]  e.g. :string, :integer, :number, :boolean, :array, :object
+      # @api public
       def type_error(value, declared_type)
         return nil if value.nil?