activeagent 1.5.0 → 1.6.0

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,9 +46,39 @@ module ActiveAgent
       # duplicates by label.
       def self.parse_all(values, **options)
         values = values.to_s.split(",") unless values.is_a?(Array)
-        values.map { |value| value.to_s.strip }.reject(&:blank?).uniq.map { |value| parse(value, **options) }
+        values.filter_map { |value| from_value(value, **options) }.uniq(&:label)
       end
 
+      # 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 [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
+
+            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 :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
       # route `name:tag` there.

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/railtie.rb

@@ -114,6 +114,16 @@ module ActiveAgent
     initializer "active_agent.inflections" do
       ActiveSupport::Inflector.inflections do |inflect|
         inflect.acronym "AI"
+
+        # "MCP" alone does not give the plural: an acronym only matches the
+        # whole word, so `mcps` still camelizes to `Mcps`, and a constant
+        # spelled `MCPs` underscores back to `mc_ps` — a name that round-trips
+        # to something no file is called.
+        #
+        # Registering the plural as its own acronym makes both directions
+        # agree: mcps <-> MCPs, alongside mcp_catalog <-> MCPCatalog.
+        inflect.acronym "MCP"
+        inflect.acronym "MCPs"
       end
     end
 

data/lib/active_agent/schema_tools.rb

@@ -0,0 +1,503 @@
+# frozen_string_literal: true
+
+require "active_agent/schema_generator"
+
+module ActiveAgent
+  # Generates a bounded, enumerable set of read-only tools from an
+  # ActiveRecord model.
+  #
+  # An agent given only generic tools (fetch_url, web_search, calculate) has
+  # nothing to call when asked a question about the host application's own
+  # data, so it answers from the prompt and invents the rest. SchemaTools
+  # closes that gap: a host declares which columns of a model an agent may
+  # filter on and which it may read back, and gets a fixed roster of
+  # function-calling tools it can hand to a provider.
+  #
+  # @example Declaring a tool set
+  #   class TicketTools < ActiveAgent::SchemaTools
+  #     model Ticket
+  #     filterable :client, :assignee, :status
+  #     returns :id, :subject, :status, :due_date
+  #     scope { |actor| TicketPolicy::Scope.new(actor, Ticket).resolve }
+  #   end
+  #
+  #   TicketTools.tool_definitions.map { |d| d[:name] }
+  #   # => ["find_tickets", "count_tickets", "get_ticket"]
+  #
+  #   TicketTools.call("find_tickets", actor: current_user, status: "open")
+  #   # => { results: [{ id: 1, subject: "...", ... }], count: 1, truncated: false }
+  #
+  # = Design properties
+  #
+  # * **Allowlist-gated.** Only columns passed to {.filterable} may appear in a
+  #   filter and only columns passed to {.returns} are ever read back. An
+  #   undeclared column is *rejected*, not dropped — silently ignoring an
+  #   unknown filter would answer a narrower question than the model asked
+  #   while looking like a success, which is how a model ends up confidently
+  #   reporting the unfiltered set. Rejecting is also what keeps the boundary
+  #   real: without it a model could filter on +users.password_digest+ one
+  #   character at a time and read a secret out of the row counts.
+  #
+  # * **Fixed roster, generated at boot.** Tools are built with +define_method+
+  #   at declaration time rather than resolved through +method_missing+,
+  #   because every consumer needs to *enumerate* the roster before any call
+  #   happens: the dashboard lists available tools, MCP +tools/list+ must
+  #   answer without being told a name first, and evals assert on an expected
+  #   +tools:+ set. A +method_missing+ design can answer "do you respond to
+  #   this?" but cannot answer "what is there?".
+  #
+  # * **Bounded results.** A +find_*+ with no filters would otherwise select
+  #   the whole table into a prompt. Every query is capped and says so via a
+  #   +truncated+ flag, so the model can tell "these are all of them" from
+  #   "these are the first #{DEFAULT_LIMIT}".
+  #
+  # * **Authorization is the host's seam, not ours.** {.scope} takes a block
+  #   receiving the caller's actor and returning a relation; the generated
+  #   tools query through it. SchemaTools does not know what an actor is and
+  #   deliberately does not try to authorize — hosts have Pundit, CanCan, or
+  #   nothing, and a framework guess would be either wrong or in the way.
+  #   Omitting +scope+ runs unscoped, which is a legitimate choice for a
+  #   single-tenant or already-trusted context.
+  class SchemaTools
+    # Default number of rows a find_* tool returns when the caller does not
+    # ask for a specific limit.
+    DEFAULT_LIMIT = 25
+
+    # Ceiling on rows a single find_* call may return, regardless of what the
+    # model passes as +limit+. A model that wants "all of them" will happily
+    # ask for 10_000; this is what stops that from becoming the prompt.
+    MAX_LIMIT = 100
+
+    # Raised when a tool call names a column outside the declared allowlists,
+    # or is otherwise outside the declared boundary.
+    class UnpermittedAttribute < ArgumentError; end
+
+    # Raised when a class declares tools without first declaring a model.
+    class MissingModel < StandardError; end
+
+    class << self
+      # Declares (or reads) the ActiveRecord class these tools expose.
+      #
+      # Calling this with a model is what triggers tool generation, so it must
+      # come before {.filterable} / {.returns} in the class body.
+      #
+      # @param klass [Class, nil] an ActiveRecord class, or nil to read
+      # @return [Class] the declared model
+      def model(klass = nil)
+        return @model if klass.nil?
+
+        unless defined?(ActiveRecord::Base) && klass < ActiveRecord::Base
+          raise ArgumentError, "#{klass} is not an ActiveRecord class"
+        end
+
+        @model = klass
+        define_tools!
+        @model
+      end
+
+      # Declares the only columns that may be used as filters.
+      #
+      # Association names are accepted and resolved to their foreign key, so a
+      # host can write +filterable :client+ rather than leaking +client_id+
+      # into the tool signature the model sees.
+      #
+      # @param names [Array<Symbol, String>] column or belongs_to association names
+      # @return [Array<Symbol>] the resolved filterable column names
+      def filterable(*names)
+        return @filterable || [] if names.empty?
+
+        @filterable = names.flatten.map { |name| resolve_column!(name) }
+        define_tools!
+        @filterable
+      end
+
+      # Declares the only columns that may be read back.
+      #
+      # @param names [Array<Symbol, String>] column names
+      # @return [Array<Symbol>] the declared return columns
+      def returns(*names)
+        return @returns || [] if names.empty?
+
+        @returns = names.flatten.map { |name| resolve_column!(name) }
+        define_tools!
+        @returns
+      end
+
+      # Registers the host's authorization seam.
+      #
+      # The block receives the actor passed to {.call} and must return an
+      # ActiveRecord relation. It is called on every tool invocation rather
+      # than memoized, because the relation depends on the actor and a cached
+      # one would serve the first caller's rows to the second.
+      #
+      # @yieldparam actor [Object] whatever the host passes as +actor:+
+      # @yieldreturn [ActiveRecord::Relation]
+      # @return [Proc, nil]
+      # Scopes reads through the host's policy for this model, found by name:
+      # Reservation -> ReservationPolicy::Scope, called as
+      # `Scope.new(actor, model).resolve`.
+      #
+      #   class ReservationTools < ActiveAgent::SchemaTools
+      #     model Reservation
+      #     scope_by_policy
+      #   end
+      #
+      # Opt-in rather than automatic: silently scoping a class that declared no
+      # scope would change what an existing tool returns, and a host may run
+      # its authorization somewhere other than a Pundit-shaped policy.
+      #
+      # Raises if the policy cannot be found, so a typo or a missing policy
+      # fails at declaration rather than quietly reading the whole table.
+      def scope_by_policy(policy = nil, method: :resolve)
+        raise MissingModel, "Declare `model` before `scope_by_policy`." unless @model
+
+        resolved = policy || "#{@model.name}Policy::Scope".safe_constantize
+        if resolved.nil?
+          raise ArgumentError,
+            "No policy found for #{@model.name}. Expected #{@model.name}Policy::Scope, " \
+            "or pass one: `scope_by_policy MyScope`."
+        end
+
+        model_class = @model
+        scope { |actor| resolved.new(actor, model_class).public_send(method) }
+      end
+
+      def scope(&block)
+        return @scope unless block
+
+        @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
+      def tool_definitions
+        (@tool_definitions || {}).values.map(&:deep_dup)
+      end
+
+      # @return [Array<String>] the names of every generated tool
+      def tool_names
+        (@tool_definitions || {}).keys
+      end
+
+      # @param name [String, Symbol]
+      # @return [Boolean] whether this class generated a tool by that name
+      def tool?(name)
+        (@tool_definitions || {}).key?(name.to_s)
+      end
+
+      # Invokes a generated tool by name.
+      #
+      # Mirrors the dashboard toolbox contract: boundary violations come back
+      # as +{ error: ... }+ rather than raising, so a model that guesses a
+      # column name gets a correction it can act on instead of killing the
+      # run. Genuine programming errors are left to raise.
+      #
+      # @param name [String, Symbol] the tool name
+      # @param actor [Object, nil] passed through to the {.scope} block
+      # @param arguments [Hash] tool arguments
+      # @return [Hash] the tool result, or +{ error: String }+
+      def call(name, actor: nil, **arguments)
+        return { error: "Unknown tool: #{name}" } unless tool?(name)
+
+        public_send(name, actor: actor, **arguments)
+      rescue UnpermittedAttribute, MissingModel => e
+        { error: e.message }
+      rescue ArgumentError => e
+        { error: "Invalid arguments for #{name}: #{e.message}" }
+      end
+
+      # Subclasses get their own declarations rather than sharing the
+      # parent's — a roster inherited by reference would let one tool class's
+      # allowlist silently widen another's.
+      def inherited(subclass)
+        super
+        subclass.instance_variable_set(:@model, @model)
+        subclass.instance_variable_set(:@filterable, (@filterable || []).dup)
+        subclass.instance_variable_set(:@returns, (@returns || []).dup)
+        subclass.instance_variable_set(:@scope, @scope)
+        subclass.instance_variable_set(:@tool_definitions, (@tool_definitions || {}).deep_dup)
+      end
+
+      # Resolves the relation a tool queries through.
+      #
+      # @api private
+      def relation_for(actor)
+        raise MissingModel, "No model declared. Call `model MyModel` first." unless @model
+
+        return @model.all unless @scope
+
+        relation = @scope.arity.zero? ? @scope.call : @scope.call(actor)
+        raise ArgumentError, "scope block must return an ActiveRecord::Relation" unless relation.respond_to?(:where)
+
+        relation
+      end
+
+      # Validates and normalizes a filter hash against the allowlist.
+      #
+      # @api private
+      # @raise [UnpermittedAttribute] if any key is not declared filterable
+      def permitted_filters!(arguments)
+        filters = arguments.each_with_object({}) do |(key, value), memo|
+          next if value.nil?
+
+          column = key.to_sym
+          unless filterable.include?(column)
+            raise UnpermittedAttribute,
+              "`#{key}` is not a filterable attribute. Allowed filters: #{filterable.join(", ")}"
+          end
+
+          memo[column] = value
+        end
+
+        filters
+      end
+
+      # Projects a record down to the declared return columns.
+      #
+      # The projection happens in SQL (+select+) as well as here, but the Ruby
+      # side is what actually guarantees the boundary: a +scope+ block that
+      # ends in +includes+ or a raw +select+ can hand back a record carrying
+      # more columns than were asked for.
+      #
+      # @api private
+      def project(record)
+        returns.index_with { |column| serialize_value(record.read_attribute(column)) }
+      end
+
+      private
+
+      # Dates and times reach the model as text, not as Ruby objects, so
+      # normalize them once here rather than letting each provider's JSON
+      # encoder pick its own format.
+      def serialize_value(value)
+        case value
+        when Time, DateTime, ActiveSupport::TimeWithZone then value.iso8601
+        when Date then value.to_s
+        else value
+        end
+      end
+
+      # Maps a declared name onto a real column, accepting belongs_to
+      # association names as a convenience for their foreign key.
+      def resolve_column!(name)
+        raise MissingModel, "Declare `model MyModel` before columns" unless @model
+
+        column = name.to_sym
+        return column if @model.column_names.include?(column.to_s)
+
+        reflection = @model.reflect_on_association(column)
+        if reflection&.belongs_to? && @model.column_names.include?(reflection.foreign_key.to_s)
+          return reflection.foreign_key.to_sym
+        end
+
+        raise UnpermittedAttribute, "`#{name}` is not a column on #{@model.name}"
+      end
+
+      # Builds the fixed tool roster.
+      #
+      # Re-run after each declaration so the definitions always reflect the
+      # current allowlists; the class body calls this two or three times
+      # during load and then never again.
+      def define_tools!
+        return unless @model
+
+        @tool_definitions = {}
+
+        define_find_tool
+        define_count_tool
+        define_get_tool
+      end
+
+      # Parameter schemas come from SchemaGenerator rather than a local type
+      # map, so a column's type, format, and enum (from an inclusion
+      # validator) are described the same way they are everywhere else in the
+      # framework.
+      def filter_properties
+        return {} if filterable.empty?
+
+        schema = ActiveAgent::SchemaGenerator::Builder.json_schema_from_model(
+          @model, include_id: true
+        )
+        properties = schema[:schema][:properties]
+
+        filterable.index_with { |column| (properties[column] || { type: "string" }).deep_dup }
+      end
+
+      def resource_name
+        @model.name.underscore
+      end
+
+      def collection_name
+        resource_name.pluralize
+      end
+
+      def define_find_tool
+        name = "find_#{collection_name}"
+        filters = filter_properties
+
+        register_tool(
+          name,
+          description: "Find #{collection_name.humanize.downcase} matching the given filters. " \
+                       "Returns at most #{MAX_LIMIT} records with these fields: #{returns.join(", ")}.",
+          properties: filters.merge(
+            limit: {
+              type: "integer",
+              description: "Maximum records to return (default #{DEFAULT_LIMIT}, max #{MAX_LIMIT})"
+            }
+          ),
+          required: []
+        )
+
+        define_singleton_method(name) do |actor: nil, limit: nil, **arguments|
+          filters = permitted_filters!(arguments)
+          capped = normalize_limit(limit)
+
+          relation = relation_for(actor).where(filters)
+          # 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
+          truncated = records.size > capped
+
+          {
+            results: records.first(capped).map { |record| project(record) },
+            count: [ records.size, capped ].min,
+            truncated: truncated
+          }
+        end
+      end
+
+      def define_count_tool
+        name = "count_#{collection_name}"
+
+        register_tool(
+          name,
+          description: "Count #{collection_name.humanize.downcase} matching the given filters.",
+          properties: filter_properties,
+          required: []
+        )
+
+        define_singleton_method(name) do |actor: nil, **arguments|
+          filters = permitted_filters!(arguments)
+
+          { count: relation_for(actor).where(filters).count }
+        end
+      end
+
+      def define_get_tool
+        name = "get_#{resource_name}"
+
+        register_tool(
+          name,
+          description: "Fetch a single #{resource_name.humanize.downcase} by id. " \
+                       "Returns these fields: #{returns.join(", ")}.",
+          properties: {
+            id: { type: "integer", description: "The record id" }
+          },
+          required: [ "id" ]
+        )
+
+        define_singleton_method(name) do |actor: nil, id: nil|
+          return { error: "id is required" } if id.nil?
+
+          # find_by through the scoped relation, not find: a record the actor
+          # cannot see must read as "not found", never as a 404-vs-403 signal
+          # the model could use to probe for existence.
+          record = relation_for(actor).find_by(id: id)
+          return { error: "No #{resource_name} found with id #{id}" } unless record
+
+          project(record)
+        end
+      end
+
+      def register_tool(name, description:, properties:, required:)
+        @tool_definitions[name] = {
+          name: name,
+          description: description,
+          parameters: {
+            type: "object",
+            properties: properties,
+            required: required
+          }
+        }
+      end
+
+      # Clamp rather than reject an oversized limit: a model asking for 1000
+      # rows wants as many as it can get, and an error would just make it ask
+      # again. The truncated flag tells it what actually happened.
+      def normalize_limit(limit)
+        return DEFAULT_LIMIT if limit.nil?
+
+        value = Integer(limit)
+        return DEFAULT_LIMIT if value <= 0
+
+        [ value, MAX_LIMIT ].min
+      end
+    end
+  end
+end

data/lib/active_agent/version.rb

@@ -1,3 +1,3 @@
 module ActiveAgent
-  VERSION = "1.5.0"
+  VERSION = "1.6.0"
 end

data/lib/active_agent.rb

@@ -92,6 +92,9 @@ module ActiveAgent
   #
   # These components are loaded on-demand when first referenced.
   autoload :Base
+  # The refusal an agent raises, and the default in Base.authorization_errors.
+  # Reachable before any agent class has loaded, so the dashboard can name it.
+  autoload :NotAuthorized, "active_agent/concerns/authorization"
   autoload :Callbacks, "active_agent/concerns/callbacks"
   autoload :Delegation, "active_agent/concerns/delegation"
   autoload :Streaming, "active_agent/concerns/streaming"
@@ -103,6 +106,8 @@ module ActiveAgent
   autoload :Previews, "active_agent/concerns/preview"
   autoload :GenerationJob
   autoload :ModelCapabilities
+  autoload :SchemaGenerator
+  autoload :SchemaTools
   autoload :Observers, "active_agent/concerns/observers"
   autoload :Provider, "active_agent/concerns/provider"
   autoload :Rescue, "active_agent/concerns/rescue"

data/lib/generators/active_agent/schema_tools/USAGE

@@ -0,0 +1,22 @@
+Description:
+    Writes a starter ActiveAgent::SchemaTools class for a model under
+    app/agent_tools. The class generates find_<records>, count_<records> and
+    get_<record> tools, and exposes nothing beyond `id` until you move a
+    column into `filterable` or `returns` — every column the model has is
+    listed, commented out, so the allowlist is a review step rather than a
+    blank page. Columns that look like secrets are left out of the list.
+
+    When <Model>Policy::Scope exists the class scopes every read through it
+    (`scope_by_policy`); otherwise a `scope` block is suggested. Pass
+    --policy or --no-policy to decide explicitly.
+
+Examples:
+    `bin/rails generate active_agent:schema_tools Reservation`
+
+    creates:
+        app/agent_tools/reservation_tools.rb
+
+    `bin/rails generate active_agent:schema_tools Reservation --policy`
+
+    scopes reads through ReservationPolicy::Scope even if it cannot be
+    found from here.