activeagent 1.5.2 → 1.6.2

data/lib/active_agent/telemetry/configuration.rb

@@ -24,6 +24,17 @@ module ActiveAgent
       # @return [Boolean] Whether to store traces in the app's own database
       attr_reader :local_storage
 
+      # The deploy every trace is stamped with (`service.version`). Unset, it
+      # is whatever ActiveAgent::Release.revision resolves — a git SHA from
+      # the conventional deploy variables — so traces from two deploys of
+      # the same service can be told apart without any host configuration.
+      attr_writer :service_version
+
+      def service_version
+        value = @service_version.respond_to?(:call) ? @service_version.call : @service_version
+        (value.presence || ActiveAgent::Release.revision)&.to_s
+      end
+
       def initialize
         super
         # The framework predates the shared gem and has always been opt-in;

data/lib/active_agent/telemetry/instrumentation.rb

@@ -58,6 +58,15 @@ module ActiveAgent
             span.set_attribute("agent.action", action_name.to_s)
             span.set_attribute("agent.provider", provider_name)
             span.set_attribute("agent.model", model_name)
+            # Which release of the agent ran: the digest of what the model was
+            # given (ActiveAgent::Release), so a dashboard can pin this trace
+            # to the version it cut on deploy.
+            if self.class.respond_to?(:release_digest)
+              span.set_attribute("agent.version", self.class.release_digest)
+              if (revision = ActiveAgent::Release.revision).present?
+                span.set_attribute("agent.revision", revision)
+              end
+            end
 
             # Add prompt span, carrying the prompt contents (instructions +
             # outbound messages) so dashboards can show what was sent.

data/lib/active_agent/telemetry/tracer.rb

@@ -169,12 +169,15 @@ module ActiveAgent
 
       # Returns default attributes for all spans.
       def default_attributes
-        {
+        attributes = {
           "service.name" => configuration.resolved_service_name,
           "service.environment" => configuration.resolved_environment,
           "telemetry.sdk.name" => "activeagent",
           "telemetry.sdk.version" => ActiveAgent::VERSION
         }
+        version = configuration.respond_to?(:service_version) ? configuration.service_version : nil
+        attributes["service.version"] = version if version.present?
+        attributes
       end
     end
   end

data/lib/active_agent/telemetry.rb

@@ -78,9 +78,31 @@ module ActiveAgent
       #   end
       def configure
         yield configuration if block_given?
+        install_instrumentation! if enabled?
         configuration
       end
 
+      # Installs generation instrumentation on ActiveAgent::Base.
+      #
+      # The railtie also does this at boot, but only for configuration already
+      # loaded by then (activeagent.yml, config.active_agent.telemetry). A host
+      # app that enables telemetry from its own initializer runs *after*
+      # railties, so that check has already seen `enabled? == false` and
+      # skipped the install — leaving telemetry enabled but nothing
+      # instrumented, and so no traces despite a valid local_store. Calling it
+      # from {.configure} as well makes the install order-independent;
+      # `instrument_telemetry!` is idempotent, so the two paths cannot
+      # double-prepend.
+      #
+      # @api private
+      # @return [void]
+      def install_instrumentation!
+        return unless defined?(ActiveAgent::Base)
+
+        ActiveAgent::Base.include(Instrumentation)
+        ActiveAgent::Base.instrument_telemetry!
+      end
+
       # Resets the configuration to defaults.
       #
       # @return [Configuration] New default configuration

data/lib/active_agent/version.rb

@@ -1,3 +1,3 @@
 module ActiveAgent
-  VERSION = "1.5.2"
+  VERSION = "1.6.2"
 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"

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.

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,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: activeagent
 version: !ruby/object:Gem::Version
-  version: 1.5.2
+  version: 1.6.2
 platform: ruby
 authors:
 - Justin Bowen
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-11 00:00:00.000000000 Z
+date: 2026-09-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actionpack
@@ -410,6 +410,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
@@ -417,6 +418,7 @@ files:
 - lib/active_agent/concerns/preview.rb
 - lib/active_agent/concerns/provider.rb
 - lib/active_agent/concerns/queueing.rb
+- lib/active_agent/concerns/release.rb
 - lib/active_agent/concerns/rescue.rb
 - lib/active_agent/concerns/streaming.rb
 - lib/active_agent/concerns/tooling.rb
@@ -578,6 +580,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