activeagent 1.5.0 → 1.6.0

data/lib/generators/active_agent/schema_tools/schema_tools_generator.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module ActiveAgent
+  module Generators
+    # Writes a starter ActiveAgent::SchemaTools class for one model:
+    #
+    #   bin/rails generate active_agent:schema_tools Reservation
+    #
+    # The class it writes exposes nothing beyond +id+ until someone uncomments
+    # a column, because which columns an agent may filter on and read back is
+    # a judgement about exposure, not a fact about the table (#440). Every
+    # column the model has is listed, commented out, minus the ones that look
+    # like secrets, so the allowlist is a review step rather than a blank page.
+    class SchemaToolsGenerator < ::Rails::Generators::NamedBase
+      source_root File.expand_path("templates", __dir__)
+
+      # Columns never suggested, whatever the model: reading one back would
+      # hand a model a credential, and filtering on one leaks it a character
+      # at a time through the row counts.
+      SECRET_COLUMNS = /password|digest|token|secret|api_key|otp|encrypted|ssn/i
+
+      class_option :policy, type: :boolean, default: nil,
+        desc: "Scope every read through <Model>Policy::Scope (default: when that policy exists)"
+
+      check_class_collision suffix: "Tools"
+
+      def create_tools_file
+        template "schema_tools.rb.tt", File.join("app/agent_tools", class_path, "#{file_name}_tools.rb")
+      end
+
+      private
+
+      # "Reservation" and "ReservationTools" both name the Reservation model.
+      def file_name # :doc:
+        @_file_name ||= super.sub(/_tools\z/i, "")
+      end
+
+      def model_class
+        @model_class ||= class_name.safe_constantize
+      end
+
+      def policy_class_name
+        "#{class_name}Policy"
+      end
+
+      def policy?
+        return options[:policy] unless options[:policy].nil?
+
+        "#{policy_class_name}::Scope".safe_constantize.present?
+      end
+
+      # [name, type] for every column the model has, or [] when the model or
+      # its table cannot be read from here (a model that does not exist yet,
+      # or a database that is not set up) — the file is still written.
+      def columns
+        @columns ||= begin
+          if model_class.respond_to?(:columns) && model_class.respond_to?(:table_exists?) && model_class.table_exists?
+            model_class.columns.map { |column| [ column.name, column.type ] }
+          else
+            []
+          end
+        rescue StandardError
+          []
+        end
+      end
+
+      def suggested_columns
+        columns.reject { |name, _type| name == "id" || name.match?(SECRET_COLUMNS) }
+      end
+
+      def secret_columns
+        columns.select { |name, _type| name.match?(SECRET_COLUMNS) }.map(&:first)
+      end
+
+      def collection_name
+        class_name.demodulize.underscore.pluralize
+      end
+
+      def resource_name
+        class_name.demodulize.underscore
+      end
+    end
+  end
+end

data/lib/generators/active_agent/schema_tools/templates/schema_tools.rb.tt

@@ -0,0 +1,48 @@
+<% module_namespacing do -%>
+# Bounded, read-only agent tools over <%= class_name %>:
+# find_<%= collection_name %>, count_<%= collection_name %>, get_<%= resource_name %>.
+#
+# Nothing is exposed until you say so. Move a column from the commented lists
+# into `filterable` (an agent may filter on it) or `returns` (an agent may
+# read it back). Each one is a judgement about exposure, not a fact about the
+# table: leave out anything a model should never see.
+class <%= class_name %>Tools < ActiveAgent::SchemaTools
+  model <%= class_name %>
+
+  filterable :id
+<% if suggested_columns.any? -%>
+  # filterable <%= suggested_columns.map { |name, _type| ":#{name}" }.join(", ") %>
+<% else -%>
+  # filterable :status, :owner_id   # columns an agent may filter on
+<% end -%>
+
+  returns :id
+<% if suggested_columns.any? -%>
+  # returns <%= suggested_columns.map { |name, _type| ":#{name}" }.join(", ") %>
+<% else -%>
+  # returns :id, :title, :status    # columns an agent may read back
+<% end -%>
+<% if suggested_columns.any? -%>
+  #
+  # Columns and their types:
+<% suggested_columns.each do |name, type| -%>
+  #   <%= name.ljust(24) %> <%= type %>
+<% end -%>
+<% end -%>
+<% if secret_columns.any? -%>
+  #
+  # Not suggested, and not to be added: <%= secret_columns.join(", ") %>.
+<% end -%>
+
+<% if policy? -%>
+  # Every read runs through <%= policy_class_name %>::Scope for the acting
+  # user, so an agent sees exactly what that user could see.
+  scope_by_policy
+<% else -%>
+  # Every read should run through a relation scoped to the acting user. Without
+  # a scope the tools read the whole table. Return <%= class_name %>.none for an
+  # actor with no access; never widen for a nil actor.
+  # scope { |actor| actor ? <%= class_name %>.where(owner: actor) : <%= class_name %>.none }
+<% end -%>
+end
+<% end -%>

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: activeagent
 version: !ruby/object:Gem::Version
-  version: 1.5.0
+  version: 1.6.0
 platform: ruby
 authors:
 - Justin Bowen
@@ -409,6 +409,7 @@ files:
 - lib/active_agent.rb
 - lib/active_agent/base.rb
 - lib/active_agent/collector.rb
+- lib/active_agent/concerns/authorization.rb
 - lib/active_agent/concerns/callbacks.rb
 - lib/active_agent/concerns/delegation.rb
 - lib/active_agent/concerns/observers.rb
@@ -562,6 +563,7 @@ files:
 - lib/active_agent/railtie.rb
 - lib/active_agent/railtie/schema_generator_extension.rb
 - lib/active_agent/schema_generator.rb
+- lib/active_agent/schema_tools.rb
 - lib/active_agent/service.rb
 - lib/active_agent/telemetry.rb
 - lib/active_agent/telemetry/configuration.rb
@@ -576,6 +578,9 @@ files:
 - lib/generators/active_agent/agent/agent_generator.rb
 - lib/generators/active_agent/install/USAGE
 - lib/generators/active_agent/install/install_generator.rb
+- lib/generators/active_agent/schema_tools/USAGE
+- lib/generators/active_agent/schema_tools/schema_tools_generator.rb
+- lib/generators/active_agent/schema_tools/templates/schema_tools.rb.tt
 - lib/generators/active_agent/templates/active_agent.yml
 - lib/generators/active_agent/templates/agent.rb.tt
 - lib/generators/active_agent/templates/application_agent.rb.tt
@@ -614,7 +619,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.16
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Rails AI Agents Framework
 test_files: []