activeagent 1.5.2 → 1.6.2

data/lib/active_agent/concerns/release.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+require "digest"
+require "json"
+
+module ActiveAgent
+  # A release of an agent is what the model is given: the provider and model,
+  # the generation options, the prompt templates on disk, the actions and the
+  # tools the class declares. {ClassMethods#release_digest} names that
+  # deterministically, so two deploys that ship the same agent share a digest
+  # and a change to any of those inputs yields a new one — without anyone
+  # bumping a number by hand.
+  #
+  # The digest is what telemetry stamps on every generation (`agent.version`)
+  # and what a dashboard cuts an AgentVersion from on deploy, so a trace, a
+  # run and an evaluation can all say which release of the agent produced
+  # them. {Release.revision} carries the deploy itself (a git SHA or a release
+  # label) alongside, when the host knows it.
+  #
+  # Class-level and memoized: in development a reload replaces the class, so
+  # the next reference recomputes it.
+  module Release
+    extend ActiveSupport::Concern
+
+    # Option keys that never belong in a manifest: credentials, and per-call
+    # state the class does not own.
+    EXCLUDED_OPTION_KEYS = %i[
+      api_key access_token secret password token trace_id messages message instructions
+    ].freeze
+    SECRET_KEY_PATTERN = /key|token|secret|password|credential/i
+
+    # How the deploy identifies itself, when it does. A host sets
+    # `ActiveAgent::Release.revision = ENV["GIT_SHA"]` (or a proc) from an
+    # initializer; otherwise the conventional deploy variables are read.
+    class << self
+      attr_writer :revision
+
+      # @return [String, nil]
+      def revision
+        value = @revision.respond_to?(:call) ? @revision.call : @revision
+        value = value.presence || ENV.values_at("SERVICE_VERSION", "GIT_SHA", "KAMAL_VERSION", "SOURCE_VERSION", "HEROKU_SLUG_COMMIT").find(&:present?)
+        value&.to_s
+      end
+
+      # Canonical JSON: sorted keys at every level, so the digest does not
+      # depend on the order anything was declared in.
+      # @api private
+      def canonical(value)
+        case value
+        when Hash then value.map { |k, v| [ k.to_s, canonical(v) ] }.sort_by(&:first).to_h
+        when Array then value.map { |v| canonical(v) }
+        when Symbol then value.to_s
+        else value
+        end
+      end
+    end
+
+    class_methods do
+      # Everything about this class that shapes a generation, as data.
+      #
+      # @return [Hash]
+      def release_manifest
+        @release_manifest ||= Release.canonical(
+          agent: name,
+          provider: release_provider,
+          model: prompt_options&.dig(:model),
+          options: release_options,
+          actions: release_actions,
+          templates: release_templates,
+          tools: release_tools,
+          delegations: release_delegations
+        )
+      end
+
+      # A short, stable identifier for {#release_manifest}: the first twelve
+      # hex characters of its SHA-256.
+      #
+      # @return [String]
+      def release_digest
+        @release_digest ||= Digest::SHA256.hexdigest(JSON.generate(release_manifest))[0, 12]
+      end
+
+      # Forgets the memoized manifest and digest — for a host that edits
+      # templates at runtime, and for tests.
+      # @return [void]
+      def reset_release!
+        @release_manifest = nil
+        @release_digest = nil
+      end
+
+      private
+
+      def release_provider
+        provider = respond_to?(:prompt_provider) ? prompt_provider : nil
+        (provider || prompt_options&.dig(:service))&.to_s
+      end
+
+      # Generation options minus credentials and per-call state. Nested
+      # hashes are walked so a token under `options: { headers: … }` is
+      # dropped too.
+      def release_options
+        strip_secrets((prompt_options || {}).except(*EXCLUDED_OPTION_KEYS, :model, :service))
+      end
+
+      def strip_secrets(value)
+        case value
+        when Hash
+          value.each_with_object({}) do |(key, inner), kept|
+            next if EXCLUDED_OPTION_KEYS.include?(key.to_sym) || key.to_s.match?(SECRET_KEY_PATTERN)
+
+            kept[key] = strip_secrets(inner)
+          end
+        when Array then value.map { |inner| strip_secrets(inner) }
+        else value
+        end
+      end
+
+      # The public actions — the prompts a caller can invoke.
+      def release_actions
+        respond_to?(:action_methods) ? action_methods.to_a.sort : []
+      end
+
+      # Every template file under this agent's view prefixes, keyed by its
+      # path relative to the view root, with a digest of its contents. The
+      # prefixes mirror View#_prefixes without an action: `app/views/<agent>/`
+      # and `app/views/agents/<agent without suffix>/`.
+      def release_templates
+        return {} if anonymous? || !respond_to?(:view_paths)
+
+        base = name.underscore
+        prefixes = [ base, "agents/#{base.delete_suffix("_agent")}" ]
+        roots = Array(view_paths).map { |path| path.respond_to?(:to_path) ? path.to_path : path.to_s }
+
+        roots.each_with_object({}) do |root, templates|
+          prefixes.each do |prefix|
+            Dir.glob(File.join(root, prefix, "**", "*")).sort.each do |file|
+              next unless File.file?(file)
+
+              relative = file.delete_prefix("#{root}/")
+              templates[relative] = Digest::SHA256.hexdigest(File.binread(file))[0, 12]
+            end
+          end
+        end
+      end
+
+      # Tool definitions the class declares itself (a host convention such as
+      # schema-derived rosters), reduced to what identifies them.
+      def release_tools
+        return [] unless respond_to?(:tool_definitions)
+
+        Array(tool_definitions).map do |definition|
+          next definition.to_s unless definition.respond_to?(:to_h)
+
+          hash = definition.to_h
+          {
+            name: (hash[:name] || hash["name"]).to_s,
+            description: (hash[:description] || hash["description"]).to_s,
+            parameters: hash[:parameters] || hash["parameters"]
+          }
+        end.sort_by { |tool| tool.is_a?(Hash) ? tool[:name] : tool }
+      end
+
+      # The delegations this class declares, by tool name.
+      def release_delegations
+        return [] unless respond_to?(:delegations)
+
+        Array(delegations).map { |tool_name, _definition| tool_name.to_s }.sort
+      end
+    end
+  end
+end

data/lib/active_agent/concerns/tooling.rb

@@ -16,7 +16,9 @@ module ActiveAgent
     # @return [Proc] callback proc that accepts (action_name, *args, **kwargs)
     def tools_function
       proc do |action_name, *args, **kwargs|
-        process(action_name, *args, **kwargs)
+        # Marked as a tool call so a refusal is reported to the model as a
+        # result rather than raised through the run (see Authorization).
+        with_tool_call { process(action_name, *args, **kwargs) }
       end
     end
   end

data/lib/active_agent/delegation/runner.rb

@@ -117,6 +117,7 @@ module ActiveAgent
       def generate(arguments)
         agent = definition.resolved_agent_class.new
         agent.params = resolved_params(arguments)
+        inherit_actor(agent)
         agent.process(definition.action, **arguments)
 
         definition.backend.apply(agent)
@@ -126,6 +127,22 @@ module ActiveAgent
         agent.process_prompt
       end
 
+      # A delegated generation runs on behalf of whoever the parent runs for.
+      # The sub-agent gets the parent's caller before its action runs, so its
+      # own before_action callbacks and any scope its tools read through decide
+      # against the same person — a parent authorized as one user must not
+      # hand its specialists an unattributed run, which a correctly written
+      # host scope reads as "no access". Hosts on an older framework, where an
+      # agent has no caller to carry, are left as they were.
+      #
+      # @param agent [ActiveAgent::Base]
+      # @return [void]
+      def inherit_actor(agent)
+        return unless owner.respond_to?(:current_user) && agent.respond_to?(:current_user=)
+
+        agent.current_user = owner.current_user
+      end
+
       # A delegated generation is part of its parent's work, so it carries the
       # parent's trace id — otherwise the sub-agent's tokens and latency land
       # in a separate trace and the budget you set has nothing to show for it.

data/lib/active_agent/evals/diagnosis.rb

@@ -12,6 +12,7 @@ module ActiveAgent
     #   tool_error               — a tool the agent called returned an error
     #   missing_capability       — the agent said no tool covers the task
     #   expected_tool_not_called — the scenario expects a tool the agent did not call
+    #   ungrounded_answer        — the answer states specifics no tool call supplied
     #   forbidden_content        — the answer contains a pattern the scenario forbids
     #   missing_content          — the answer lacks a pattern the scenario expects
     #   low_quality              — the answer scored below the threshold
@@ -21,7 +22,7 @@ module ActiveAgent
     # Returns nil for a passing result.
     class Diagnosis
       FAULTS = %w[
-        run_error tool_error missing_capability expected_tool_not_called
+        run_error tool_error missing_capability expected_tool_not_called ungrounded_answer
         forbidden_content missing_content low_quality judge_unavailable
       ].freeze
 
@@ -38,6 +39,19 @@ module ActiveAgent
         /\bcan(?:'|no)t (?:be )?(?:done|determined|answered) with (?:the|my) (?:current|available) tools\b/i
       ].freeze
 
+      # Phrasings that state a specific fact — a record id, a date, a count of
+      # things — which an agent that called no tool can only have invented.
+      # Deliberately narrow: a number inside prose ("here are three options",
+      # "within 30 days") is not a claim about data, and a false positive here
+      # fails a scenario that may have passed on its merits.
+      SPECIFIC_CLAIMS = [
+        /#\d+\b/,
+        /\b\d{4}-\d{2}-\d{2}\b/,
+        /\b(?:you have|there are|there is|we have|I found|found|showing|a total of)\s+(?:\*\*)?\d+\b/i,
+        /\b\d+\s+(?:\*\*)?(?:open|overdue|pending|active|closed|resolved|completed|unpaid|outstanding|new|matching|
+          records?|results?|rows?|entries|items?|tickets?|orders?|tasks?|issues?|invoices?|customers?|users?|milestones?)\b/ix
+      ].freeze
+
       Result = Struct.new(:fault, :summary, :recommendation, :evidence, keyword_init: true) do
         def to_h
           {
@@ -76,7 +90,7 @@ module ActiveAgent
       end
 
       def call
-        run_error || tool_error || missing_capability || expected_tool_not_called ||
+        run_error || tool_error || missing_capability || expected_tool_not_called || ungrounded_answer ||
           forbidden_content || missing_content || low_quality
       end
 
@@ -178,16 +192,58 @@ module ActiveAgent
             "#{agent} answered with #{called_tools.uniq.join(', ')} instead of #{expected.join(', ')}. Sharpen " \
             "both tools' descriptions so the model can tell them apart, or say in the instructions which tool " \
             "answers this kind of task."
+          elsif asserts_specifics?
+            "#{expected.join(', ')} is available but #{agent.downcase} answered without calling any tool and " \
+            "stated specifics it could not have looked up (\"#{claim_excerpt}\"). Treat the answer as invented: " \
+            "instruct it to answer this kind of task only from a tool result, and to say so when it has none."
           else
             "#{expected.join(', ')} is available but #{agent.downcase} answered without calling any tool. Tell " \
             "it in the instructions to prefer tool-backed answers for this kind of task, and check the tool's " \
             "description says what it returns."
           end
 
-        result("expected_tool_not_called",
-               "Expected #{expected.join(' or ')} to be called; #{agent.downcase} called " \
-               "#{called_tools.uniq.presence&.join(', ') || 'nothing'}.",
-               recommendation, "expected" => expected, "called" => called_tools, "unavailable" => unavailable)
+        summary = "Expected #{expected.join(' or ')} to be called; #{agent.downcase} called " \
+                  "#{called_tools.uniq.presence&.join(', ') || 'nothing'}"
+        summary += " and answered with specifics no tool supplied" if called_tools.empty? && asserts_specifics?
+
+        result("expected_tool_not_called", "#{summary}.", recommendation,
+               "expected" => expected, "called" => called_tools, "unavailable" => unavailable,
+               "ungrounded" => (called_tools.empty? && asserts_specifics?) || nil, "claim" => (claim_excerpt if called_tools.empty?))
+      end
+
+      # The answer states specifics — a count, an id, a date — that no tool
+      # call could have supplied. Reached only when the scenario names no
+      # expected tool (expected_tool_not_called reports the same fabrication
+      # otherwise) and only for an agent that had tools to call: one with
+      # none answers from its instructions by design, and whether that is
+      # acceptable is the judge's call, not a mechanical one.
+      def ungrounded_answer
+        return nil if @available_tools.empty? || called_tools.any?
+        return nil unless asserts_specifics?
+
+        result("ungrounded_answer",
+               "#{agent} stated specifics (\"#{claim_excerpt}\") without calling any tool that could have supplied them.",
+               "Nothing in the answer came from a tool, so the figures in it are invented. Tell #{agent.downcase} in its " \
+               "instructions to answer this kind of task only from a tool result and to say when it has none; if none of " \
+               "#{@available_tools.join(', ')} returns this data, add a tool that does.",
+               "claim" => claim_excerpt, "tools_available" => @available_tools)
+      end
+
+      def asserts_specifics?
+        specific_claim.present?
+      end
+
+      def specific_claim
+        return @specific_claim if defined?(@specific_claim)
+
+        @specific_claim = SPECIFIC_CLAIMS.lazy.filter_map { |pattern| answer.match(pattern) }.first
+      end
+
+      def claim_excerpt
+        match = specific_claim
+        return nil unless match
+
+        answer[[ match.begin(0) - 40, 0 ].max, 120].to_s.strip
       end
 
       def forbidden_content

data/lib/active_agent/evals/judge.rb

@@ -24,6 +24,11 @@ module ActiveAgent
       # @yieldparam instructions [String] the system prompt
       # @yieldparam prompt [String] the user prompt
       # @yieldreturn [String] the completion text
+      # How much of a scenario's notes the judge reads. Where a suite's notes
+      # are its grading rubric, a "Must not…" clause tends to come last, and a
+      # judge that never saw it recommends against it.
+      NOTES_LIMIT = 1_500
+
       def initialize(label:, &generate)
         raise ArgumentError, "Judge.new needs a block that returns the model's completion" unless generate
 
@@ -64,7 +69,7 @@ module ActiveAgent
           ---
           #{scenario.prompt}
           ---
-          #{"Context for the evaluator: #{scenario.notes.truncate(300)}\n" if scenario.notes.present?}
+          #{"Context for the evaluator: #{scenario.notes.truncate(NOTES_LIMIT)}\n" if scenario.notes.present?}
           The assistant answered:
           ---
           #{answer.to_s.truncate(4_000)}
@@ -99,7 +104,7 @@ module ActiveAgent
           Scenario (the user's message):
           #{scenario.prompt}
           #{"Expected tools: #{scenario.expected_tools.join(', ')}" if scenario.expected_tools.any?}
-          #{"Notes: #{scenario.notes.truncate(300)}" if scenario.notes.present?}
+          #{"Notes: #{scenario.notes.truncate(NOTES_LIMIT)}" if scenario.notes.present?}
 
           Tools the agent called:
           #{calls.presence || '(none)'}

data/lib/active_agent/evals/model_spec.rb

@@ -46,22 +46,38 @@ module ActiveAgent
       # duplicates by label.
       def self.parse_all(values, **options)
         values = values.to_s.split(",") unless values.is_a?(Array)
-        values.map { |value| coerce(value) }.reject(&:blank?).uniq.map { |value| parse(value, **options) }
+        values.filter_map { |value| from_value(value, **options) }.uniq(&:label)
       end
 
-      # The label of one requested model. A caller that round-trips a spec —
-      # the dashboard persists `specs.map(&:to_h)` and hands it back on a
-      # re-run — sends a Hash, whose `to_s` is the inspected Hash and reaches
-      # the provider as the model ID: `{"label" => "openrouter/gpt-4o-mini",
-      # ...} is not a valid model ID`.
+      # One requested model, from the text a user typed or from a spec handed
+      # back whole. The dashboard persists `specs.map(&:to_h)` and returns it on
+      # a re-run, so a value may be a Hash: one that names both `provider` and
+      # `model` is rebuilt exactly as it ran, because re-parsing its label
+      # would route a vendor-prefixed model the wrong way —
+      # `"anthropic/claude-sonnet-4.5"` run through OpenRouter came back as
+      # Anthropic's own `claude-sonnet-4.5` the moment that provider was
+      # installed. A Hash naming only a label or a model is parsed from that
+      # text; anything naming nothing is dropped.
       #
-      # @return [String, nil] nil when the value names no model
-      def self.coerce(value)
-        return value.to_h.stringify_keys.values_at("label", "model").compact.first.to_s.strip if value.respond_to?(:to_h) && !value.is_a?(String)
+      # @return [ModelSpec, nil]
+      def self.from_value(value, **options)
+        text =
+          if value.respond_to?(:to_h) && !value.is_a?(String)
+            hash = value.to_h.stringify_keys
+            if hash["provider"].present? && hash["model"].present?
+              return new(label: hash["label"].presence || hash["model"], provider: hash["provider"], model: hash["model"])
+            end
 
-        value.to_s.strip
+            hash.values_at("label", "model").compact.first.to_s.strip
+          else
+            value.to_s.strip
+          end
+
+        return nil if text.blank?
+
+        parse(text, **options)
       end
-      private_class_method :coerce
+      private_class_method :from_value
 
       # The provider a bare model name runs under. A rule whose provider the
       # caller does not offer is skipped, so an app without Ollama does not

data/lib/active_agent/evals/runner.rb

@@ -28,7 +28,7 @@ module ActiveAgent
     class Runner
       # Faults where a judge can add something the evidence alone cannot: what
       # tool to add, or how to change the instructions.
-      DEFAULT_REFINE_FAULTS = %w[missing_capability expected_tool_not_called low_quality missing_content].freeze
+      DEFAULT_REFINE_FAULTS = %w[missing_capability expected_tool_not_called ungrounded_answer low_quality missing_content].freeze
       DEFAULT_JUDGE_LIMIT = 25
 
       attr_reader :scenarios, :models, :criteria, :judge, :threshold

data/lib/active_agent/evals/scorer.rb

@@ -49,7 +49,10 @@ module ActiveAgent
           hit = scenario.forbidden_patterns.any? { |pattern| self.class.matches_pattern?(answer, pattern) }
           scores["forbidden_content"] = hit ? 0.0 : 1.0
         end
-        if replay.tool_calls.any?
+        # A tool that ran without erroring is evidence only when it is one the
+        # scenario expected: a wrong tool that succeeded used to outscore
+        # calling nothing at all.
+        if replay.tool_calls.any? && (scenario.expected_tools.empty? || (scenario.expected_tools & replay.tool_names).any?)
           scores["tools_succeeded"] = replay.failed_tool_calls.any? ? 0.0 : 1.0
         end
 

data/lib/active_agent/generation_job.rb

@@ -18,8 +18,14 @@ module ActiveAgent
 
     rescue_from StandardError, with: :handle_exception_with_agent_class
 
-    def perform(agent, agent_method, generation_method, args:, kwargs: nil, params: nil)
+    # +actor+ is the caller the generation runs on behalf of
+    # (ActiveAgent::Authorization). ActiveJob serializes it like any other
+    # argument, so a record arrives as the same record the caller passed and
+    # the agent's authorization callbacks decide against a real user rather
+    # than against nil.
+    def perform(agent, agent_method, generation_method, args:, kwargs: nil, params: nil, actor: nil)
       agent_class = params ? agent.constantize.with(params) : agent.constantize
+      agent_class = agent_class.as(actor) if actor
       prompt = if kwargs
         agent_class.public_send(agent_method, *args, **kwargs)
       else

data/lib/active_agent/schema_tools.rb

@@ -68,6 +68,21 @@ module ActiveAgent
     # ask for 10_000; this is what stops that from becoming the prompt.
     MAX_LIMIT = 100
 
+    # Column types a range comparison is offered for. Strings and booleans
+    # are deliberately absent: a lexical `>` on a name column answers a
+    # question nobody asked.
+    RANGE_FILTERABLE_TYPES = %i[date datetime time integer float decimal].freeze
+
+    # The comparison operators a range filter may use, mapped to the Arel
+    # predicate that builds them. Names are the ones models reach for
+    # unprompted (`before`/`after` for dates, `lt`/`gte` for numbers), so a
+    # reasonable guess resolves instead of erroring.
+    RANGE_OPERATORS = {
+      "before" => :lt, "after" => :gt,
+      "lt" => :lt, "lte" => :lteq, "gt" => :gt, "gte" => :gteq,
+      "on_or_before" => :lteq, "on_or_after" => :gteq
+    }.freeze
+
     # Raised when a tool call names a column outside the declared allowlists,
     # or is otherwise outside the declared boundary.
     class UnpermittedAttribute < ArgumentError; end
@@ -168,6 +183,71 @@ module ActiveAgent
         @scope = block
       end
 
+      # Runtime-defined tool classes, keyed by model name. A definition built
+      # by {.define} replaces the previous one for its model, so a registry
+      # that is rebuilt on every change — from a table, from a dashboard
+      # edit — holds one class per model rather than one per rebuild.
+      #
+      # @return [Hash{String => Class}]
+      def registry
+        @registry ||= {}
+      end
+
+      # Builds a tool class from a declaration rather than from a file:
+      #
+      #   ActiveAgent::SchemaTools.define(Reservation,
+      #     filterable: %i[status guest_id],
+      #     returns: %i[id status guest_id arrives_on],
+      #     policy: true)   # ReservationPolicy::Scope, as scope_by_policy would
+      #
+      # The class behaves exactly as a file-defined one — same roster, same
+      # allowlists, same +call+ — and is named "<Model>Tools" for logs and
+      # telemetry. It is marked runtime-built so discovery does not read it
+      # back out of +descendants+ (where every class ever built stays until
+      # collected), and registered under its model, replacing whatever the
+      # registry held: that is what keeps a rebuild from accumulating classes
+      # (#441). +scope:+ takes a lambda or proc receiving the actor; +policy:+
+      # resolves the model's policy by name; neither means unscoped, as for a
+      # file-defined class.
+      #
+      # @param model [Class] an ActiveRecord class
+      # @param filterable [Array<Symbol, String>]
+      # @param returns [Array<Symbol, String>]
+      # @param scope [Proc, nil]
+      # @param policy [Boolean, Class] true for the conventional policy, or the policy class
+      # @param name [String, nil] the class name, "<Model>Tools" by default
+      # @return [Class]
+      def define(model, filterable: [], returns: [], scope: nil, policy: false, name: nil)
+        klass = Class.new(self)
+        klass.instance_variable_set(:@runtime, true)
+        class_name = name || "#{model.name}Tools"
+        klass.define_singleton_method(:name) { class_name }
+        klass.model(model)
+        klass.filterable(*filterable) if filterable.present?
+        klass.returns(*returns) if returns.present?
+        klass.scope_by_policy(policy == true ? nil : policy) if policy
+        klass.scope(&scope) if scope
+
+        registry[model.name] = klass
+      end
+
+      # Drops the runtime definition for +model+; discovery stops offering it.
+      #
+      # @param model [Class, String]
+      # @return [Class, nil] the class that was registered
+      def undefine(model)
+        registry.delete(model.respond_to?(:name) ? model.name : model.to_s)
+      end
+
+      # Whether this class was built by {.define} rather than loaded from a
+      # file. Discovery reads runtime classes from {.registry}, never from
+      # +descendants+, so a superseded one is not offered twice.
+      #
+      # @return [Boolean]
+      def runtime?
+        @runtime == true
+      end
+
       # The full, fixed tool roster in provider function-calling format.
       #
       # @return [Array<Hash>] tool definitions with :name, :description, :parameters
@@ -235,8 +315,13 @@ module ActiveAgent
 
       # Validates and normalizes a filter hash against the allowlist.
       #
+      # A filter value is normally matched for equality. A Hash value instead
+      # declares a range — `{ "before" => "2026-01-01" }`, `{ "gte" => 10 }` —
+      # and may carry two bounds at once to express a window.
+      #
       # @api private
-      # @raise [UnpermittedAttribute] if any key is not declared filterable
+      # @raise [UnpermittedAttribute] if any key is not declared filterable,
+      #   or a range names an operator that does not exist
       def permitted_filters!(arguments)
         filters = arguments.each_with_object({}) do |(key, value), memo|
           next if value.nil?
@@ -253,6 +338,54 @@ module ActiveAgent
         filters
       end
 
+      # Splits filters into equality pairs and range predicates.
+      #
+      # Kept separate from {.permitted_filters!} because the two halves are
+      # applied differently: equality goes to `where(hash)`, ranges have to be
+      # built through Arel.
+      #
+      # @api private
+      # @return [Array(Hash, Array<Arel::Nodes::Node>)]
+      def partition_filters!(filters)
+        equality = {}
+        ranges   = []
+
+        filters.each do |column, value|
+          if value.is_a?(Hash)
+            ranges.concat(range_predicates!(column, value))
+          else
+            equality[column] = value
+          end
+        end
+
+        [ equality, ranges ]
+      end
+
+      # Builds Arel predicates for one column's range hash.
+      #
+      # Rails silently turns `where(col: { "before" => x })` into `col = NULL`,
+      # which matches nothing and reports zero rather than failing — the worst
+      # outcome for an agent, which reads it as a truthful empty answer. So an
+      # unknown operator is rejected loudly here instead.
+      #
+      # @api private
+      # @raise [UnpermittedAttribute] on an unknown operator
+      def range_predicates!(column, value)
+        arel = @model.arel_table[column]
+        type = @model.type_for_attribute(column)
+
+        value.map do |operator, operand|
+          predicate = RANGE_OPERATORS[operator.to_s]
+          unless predicate
+            raise UnpermittedAttribute,
+              "`#{operator}` is not a valid comparison for `#{column}`. " \
+              "Allowed comparisons: #{RANGE_OPERATORS.keys.join(", ")}"
+          end
+
+          arel.public_send(predicate, type.cast(operand))
+        end
+      end
+
       # Projects a record down to the declared return columns.
       #
       # The projection happens in SQL (+select+) as well as here, but the Ruby
@@ -321,7 +454,40 @@ module ActiveAgent
         )
         properties = schema[:schema][:properties]
 
-        filterable.index_with { |column| (properties[column] || { type: "string" }).deep_dup }
+        filterable.index_with do |column|
+          scalar = (properties[column] || { type: "string" }).deep_dup
+          range_filterable?(column) ? with_range_form(column, scalar) : scalar
+        end
+      end
+
+      # Dates, times and numbers are the columns a question like "overdue" or
+      # "more than 10" actually needs a comparison on.
+      def range_filterable?(column)
+        RANGE_FILTERABLE_TYPES.include?(@model.type_for_attribute(column).type)
+      end
+
+      # Offers a column as either a scalar (equality) or a range object.
+      #
+      # Without this the range form works but is undiscoverable: a model shown
+      # only `{type: "string", format: "date"}` has no way to know it may ask
+      # for `before`, and answers date questions with an equality match or no
+      # filter at all.
+      def with_range_form(column, scalar)
+        operand = scalar.slice(:type, :format)
+        description = scalar[:description]
+
+        {
+          description: [ description, "Accepts an exact value, or a range object such as " \
+            "{\"before\": ...} / {\"gte\": ...} (#{RANGE_OPERATORS.keys.join(", ")})." ].compact.join(" "),
+          anyOf: [
+            scalar.except(:description),
+            {
+              type: "object",
+              properties: RANGE_OPERATORS.keys.index_with { operand.dup },
+              additionalProperties: false
+            }
+          ]
+        }
       end
 
       def resource_name
@@ -350,10 +516,10 @@ module ActiveAgent
         )
 
         define_singleton_method(name) do |actor: nil, limit: nil, **arguments|
-          filters = permitted_filters!(arguments)
+          equality, ranges = partition_filters!(permitted_filters!(arguments))
           capped = normalize_limit(limit)
 
-          relation = relation_for(actor).where(filters)
+          relation = ranges.reduce(relation_for(actor).where(equality)) { |rel, p| rel.where(p) }
           # One extra row distinguishes "exactly at the limit" from "more than
           # the limit", without a second COUNT query.
           records = relation.limit(capped + 1).to_a
@@ -378,9 +544,10 @@ module ActiveAgent
         )
 
         define_singleton_method(name) do |actor: nil, **arguments|
-          filters = permitted_filters!(arguments)
+          equality, ranges = partition_filters!(permitted_filters!(arguments))
+          relation = ranges.reduce(relation_for(actor).where(equality)) { |rel, p| rel.where(p) }
 
-          { count: relation_for(actor).where(filters).count }
+          { count: relation.count }
         end
       end