activeagent 1.0.1 → 1.0.2

data/lib/active_agent/telemetry/tracer.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+module ActiveAgent
+  module Telemetry
+    # Manages trace creation and lifecycle.
+    #
+    # The Tracer creates traces, manages the current trace context,
+    # and coordinates with the Reporter for async transmission.
+    #
+    # @example Basic usage
+    #   tracer = Tracer.new(configuration)
+    #   tracer.trace("MyAgent.greet") do |span|
+    #     span.set_attribute("user_id", 123)
+    #     span.add_span("llm.generate", span_type: :llm)
+    #   end
+    #
+    class Tracer
+      # @return [Configuration] Telemetry configuration
+      attr_reader :configuration
+
+      # @return [Reporter] The reporter for sending traces
+      attr_reader :reporter
+
+      # Thread-local storage for current trace context
+      CURRENT_SPAN_KEY = :active_agent_telemetry_current_span
+
+      def initialize(configuration)
+        @configuration = configuration
+        @reporter = Reporter.new(configuration)
+        @mutex = Mutex.new
+      end
+
+      # Creates and executes a new trace.
+      #
+      # @param name [String] Trace name (typically "AgentClass.action")
+      # @param attributes [Hash] Root span attributes
+      # @yield [span] Yields the root span for adding child spans
+      # @return [Object] Result of the block
+      #
+      # @example
+      #   tracer.trace("WeatherAgent.forecast") do |span|
+      #     span.set_attribute("location", "Seattle")
+      #     result = do_llm_call
+      #     span.set_tokens(input: 100, output: 50)
+      #     result
+      #   end
+      def trace(name, **attributes, &block)
+        return yield(Telemetry::NullSpan.new) unless should_trace?
+
+        trace_id = generate_trace_id
+        root_span = Span.new(
+          name,
+          trace_id: trace_id,
+          span_type: :root,
+          **default_attributes.merge(attributes)
+        )
+
+        with_span(root_span) do
+          result = yield(root_span)
+          root_span.finish
+          report_trace(root_span)
+          result
+        end
+      rescue StandardError => e
+        root_span&.record_error(e)
+        root_span&.finish
+        report_trace(root_span) if root_span
+        raise
+      end
+
+      # Creates a standalone span (not within a trace block).
+      #
+      # @param name [String] Span name
+      # @param attributes [Hash] Span attributes
+      # @return [Span] The created span
+      def span(name, **attributes)
+        return Telemetry::NullSpan.new unless should_trace?
+
+        current = current_span
+        if current
+          current.add_span(name, **attributes)
+        else
+          Span.new(name, trace_id: generate_trace_id, **default_attributes.merge(attributes))
+        end
+      end
+
+      # Returns the current span from thread-local storage.
+      #
+      # @return [Span, nil] Current span or nil
+      def current_span
+        Thread.current[CURRENT_SPAN_KEY]
+      end
+
+      # Flushes buffered traces immediately.
+      #
+      # @return [void]
+      def flush
+        reporter.flush
+      end
+
+      # Shuts down the tracer and reporter.
+      #
+      # @return [void]
+      def shutdown
+        reporter.shutdown
+      end
+
+      private
+
+      # Executes block with span as current context.
+      #
+      # @param span [Span] Span to set as current
+      # @yield Block to execute
+      # @return [Object] Result of block
+      def with_span(span)
+        previous = Thread.current[CURRENT_SPAN_KEY]
+        Thread.current[CURRENT_SPAN_KEY] = span
+        yield
+      ensure
+        Thread.current[CURRENT_SPAN_KEY] = previous
+      end
+
+      # Reports a completed trace to the reporter.
+      #
+      # @param span [Span] Root span of the trace
+      def report_trace(span)
+        reporter.report(build_trace_payload(span))
+      end
+
+      # Builds the trace payload for transmission.
+      #
+      # @param root_span [Span] Root span
+      # @return [Hash] Trace payload
+      def build_trace_payload(root_span)
+        {
+          trace_id: root_span.trace_id,
+          service_name: configuration.resolved_service_name,
+          environment: configuration.environment,
+          timestamp: Time.current.iso8601(6),
+          resource_attributes: configuration.resource_attributes,
+          spans: flatten_spans(root_span)
+        }
+      end
+
+      # Flattens span hierarchy into array.
+      #
+      # @param span [Span] Root span
+      # @return [Array<Hash>] Flattened span data
+      def flatten_spans(span)
+        result = [ span.to_h.except(:children) ]
+        span.children.each do |child|
+          result.concat(flatten_spans(child))
+        end
+        result
+      end
+
+      # Returns whether this trace should be sampled.
+      #
+      # @return [Boolean]
+      def should_trace?
+        configuration.enabled? && configuration.configured? && configuration.should_sample?
+      end
+
+      # Generates a unique trace ID.
+      #
+      # @return [String] 32-character hex trace ID
+      def generate_trace_id
+        SecureRandom.hex(16)
+      end
+
+      # Returns default attributes for all spans.
+      #
+      # @return [Hash] Default attributes
+      def default_attributes
+        {
+          "service.name" => configuration.resolved_service_name,
+          "service.environment" => configuration.environment,
+          "telemetry.sdk.name" => "activeagent",
+          "telemetry.sdk.version" => ActiveAgent::VERSION
+        }
+      end
+    end
+  end
+end

data/lib/active_agent/telemetry.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "securerandom"
+
+module ActiveAgent
+  # Telemetry module for collecting and reporting agent traces.
+  #
+  # Provides optional observability by capturing agent generation traces,
+  # tool calls, token usage, and errors. Reports to a configured endpoint
+  # (self-hosted or ActiveAgents.ai hosted service).
+  #
+  # = Features
+  #
+  # * **Trace Collection**: Captures full generation lifecycle with spans
+  # * **Token Tracking**: Records input/output/thinking tokens per generation
+  # * **Tool Call Tracing**: Captures tool invocations with arguments and results
+  # * **Error Tracking**: Records errors with backtraces
+  # * **Async Reporting**: Non-blocking HTTP reporting with background thread
+  #
+  # = Configuration
+  #
+  # Configure in your Rails initializer or activeagent.yml:
+  #
+  # @example Basic configuration
+  #   ActiveAgent::Telemetry.configure do |config|
+  #     config.enabled = true
+  #     config.endpoint = "https://api.activeagents.ai/v1/traces"
+  #     config.api_key = Rails.application.credentials.dig(:activeagents, :api_key)
+  #   end
+  #
+  # @example YAML configuration (config/activeagent.yml)
+  #   telemetry:
+  #     enabled: true
+  #     endpoint: https://api.activeagents.ai/v1/traces
+  #     api_key: <%= Rails.application.credentials.dig(:activeagents, :api_key) %>
+  #     sample_rate: 1.0
+  #     batch_size: 100
+  #     flush_interval: 5
+  #
+  # @example Self-hosted endpoint
+  #   ActiveAgent::Telemetry.configure do |config|
+  #     config.endpoint = "https://observability.mycompany.com/v1/traces"
+  #     config.api_key = ENV["TELEMETRY_API_KEY"]
+  #   end
+  #
+  # @see ActiveAgent::Telemetry::Configuration
+  # @see ActiveAgent::Telemetry::Tracer
+  module Telemetry
+    extend ActiveSupport::Autoload
+
+    autoload :Configuration
+    autoload :Tracer
+    autoload :Span
+    autoload :Reporter
+    autoload :Instrumentation
+
+    class << self
+      # Returns the telemetry configuration instance.
+      #
+      # @return [Configuration] The configuration instance
+      def configuration
+        @configuration ||= Configuration.new
+      end
+
+      # Configures telemetry with a block.
+      #
+      # @yield [config] Yields the configuration instance
+      # @yieldparam config [Configuration] The configuration to modify
+      # @return [Configuration] The modified configuration
+      #
+      # @example
+      #   ActiveAgent::Telemetry.configure do |config|
+      #     config.enabled = true
+      #     config.endpoint = "https://api.activeagents.ai/v1/traces"
+      #     config.api_key = "your-api-key"
+      #   end
+      def configure
+        yield configuration if block_given?
+        configuration
+      end
+
+      # Resets the configuration to defaults.
+      #
+      # @return [Configuration] New default configuration
+      def reset_configuration!
+        @configuration = Configuration.new
+      end
+
+      # Returns whether telemetry is enabled and configured.
+      #
+      # @return [Boolean] True if telemetry should collect and report
+      def enabled?
+        configuration.enabled? && configuration.configured?
+      end
+
+      # Returns the global tracer instance.
+      #
+      # @return [Tracer] The tracer instance
+      def tracer
+        @tracer ||= Tracer.new(configuration)
+      end
+
+      # Starts a new trace for an agent generation.
+      #
+      # @param name [String] Name of the trace (typically agent.action)
+      # @param attributes [Hash] Additional trace attributes
+      # @yield [trace] Yields the trace for adding spans
+      # @return [Span] The root span of the trace
+      #
+      # @example
+      #   ActiveAgent::Telemetry.trace("WeatherAgent.forecast") do |trace|
+      #     trace.add_span("llm.generate", provider: "anthropic")
+      #     trace.set_tokens(input: 100, output: 50)
+      #   end
+      def trace(name, **attributes, &block)
+        return yield(NullSpan.new) unless enabled?
+
+        tracer.trace(name, **attributes, &block)
+      end
+
+      # Records a standalone span (outside of a trace context).
+      #
+      # @param name [String] Span name
+      # @param attributes [Hash] Span attributes
+      # @return [Span] The created span
+      def span(name, **attributes)
+        return NullSpan.new unless enabled?
+
+        tracer.span(name, **attributes)
+      end
+
+      # Flushes any buffered traces immediately.
+      #
+      # @return [void]
+      def flush
+        tracer.flush if enabled?
+      end
+
+      # Shuts down telemetry, flushing remaining traces.
+      #
+      # @return [void]
+      def shutdown
+        tracer.shutdown if @tracer
+      end
+    end
+
+    # Null span implementation for when telemetry is disabled.
+    #
+    # Provides no-op methods that match Span interface to avoid
+    # nil checks throughout the codebase.
+    class NullSpan
+      def add_span(name, **attributes); self; end
+      def set_attribute(key, value); self; end
+      def set_tokens(input: 0, output: 0, thinking: 0); self; end
+      def set_status(status, message = nil); self; end
+      def record_error(error); self; end
+      def finish; self; end
+    end
+  end
+end

data/lib/active_agent/version.rb

@@ -1,3 +1,3 @@
 module ActiveAgent
-  VERSION = "1.0.1"
+  VERSION = "1.0.2"
 end

data/lib/active_agent.rb

@@ -106,6 +106,8 @@ module ActiveAgent
   autoload :Rescue, "active_agent/concerns/rescue"
   autoload :Tooling, "active_agent/concerns/tooling"
   autoload :View, "active_agent/concerns/view"
+  autoload :Telemetry
+  autoload :Dashboard
 
   class << self
     # Eagerly loads all ActiveAgent components and descendant agent classes.

data/lib/generators/active_agent/dashboard/install/install_generator.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+
+module ActiveAgent
+  module Dashboard
+    module Generators
+      # Generator for installing the ActiveAgent Dashboard engine.
+      #
+      # Usage:
+      #   rails generate active_agent:dashboard:install
+      #
+      # This will:
+      # - Copy migration files for all dashboard models
+      # - Create an initializer for configuration
+      # - Add the engine mount to routes.rb
+      # - Seed default agent templates
+      #
+      class InstallGenerator < Rails::Generators::Base
+        include ActiveRecord::Generators::Migration
+
+        source_root File.expand_path("templates", __dir__)
+
+        class_option :multi_tenant, type: :boolean, default: false,
+          desc: "Configure for multi-tenant mode with account association"
+
+        class_option :skip_migrations, type: :boolean, default: false,
+          desc: "Skip copying migration files"
+
+        class_option :skip_routes, type: :boolean, default: false,
+          desc: "Skip adding route mount"
+
+        def copy_migrations
+          return if options[:skip_migrations]
+
+          migration_template "migrations/create_active_agent_agents.rb",
+            "db/migrate/create_active_agent_agents.rb"
+
+          migration_template "migrations/create_active_agent_agent_versions.rb",
+            "db/migrate/create_active_agent_agent_versions.rb"
+
+          migration_template "migrations/create_active_agent_agent_runs.rb",
+            "db/migrate/create_active_agent_agent_runs.rb"
+
+          migration_template "migrations/create_active_agent_agent_templates.rb",
+            "db/migrate/create_active_agent_agent_templates.rb"
+
+          migration_template "migrations/create_active_agent_sandbox_sessions.rb",
+            "db/migrate/create_active_agent_sandbox_sessions.rb"
+
+          migration_template "migrations/create_active_agent_sandbox_runs.rb",
+            "db/migrate/create_active_agent_sandbox_runs.rb"
+
+          migration_template "migrations/create_active_agent_session_recordings.rb",
+            "db/migrate/create_active_agent_session_recordings.rb"
+
+          migration_template "migrations/create_active_agent_telemetry_traces.rb",
+            "db/migrate/create_active_agent_telemetry_traces.rb"
+        end
+
+        def create_initializer
+          template "initializer.rb", "config/initializers/active_agent_dashboard.rb"
+        end
+
+        def mount_engine
+          return if options[:skip_routes]
+
+          route 'mount ActiveAgent::Dashboard::Engine => "/active_agent"'
+        end
+
+        def show_post_install
+          say ""
+          say "ActiveAgent Dashboard installed!", :green
+          say ""
+          say "Next steps:"
+          say "  1. Run migrations: rails db:migrate"
+          say "  2. Seed templates:  rails active_agent:dashboard:seed"
+          say "  3. Configure authentication in config/initializers/active_agent_dashboard.rb"
+          say "  4. Visit /active_agent to access the dashboard"
+          say ""
+        end
+
+        private
+
+        def migration_version
+          "[#{ActiveRecord::Migration.current_version}]"
+        end
+
+        def multi_tenant?
+          options[:multi_tenant]
+        end
+      end
+    end
+  end
+end

data/lib/generators/active_agent/dashboard/install/templates/initializer.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+# ActiveAgent Dashboard Configuration
+#
+# This initializer configures the ActiveAgent Dashboard engine.
+# See https://docs.activeagents.ai/dashboard for full documentation.
+
+ActiveAgent::Dashboard.configure do |config|
+  # ==========================================================================
+  # Authentication
+  # ==========================================================================
+
+  # Set an authentication method that will be called on all dashboard controllers.
+  # This should authenticate the user and redirect/raise if unauthorized.
+  #
+  # Examples:
+  #   config.authentication_method = ->(controller) { controller.authenticate_admin! }
+  #   config.authentication_method = ->(controller) { controller.authenticate_user! }
+  #
+  # config.authentication_method = nil
+
+<% if multi_tenant? -%>
+  # ==========================================================================
+  # Multi-tenant Mode
+  # ==========================================================================
+
+  # Enable multi-tenant mode for SaaS deployments with multiple accounts.
+  config.multi_tenant = true
+
+  # The Account model class name
+  config.account_class = "Account"
+
+  # The User model class name
+  config.user_class = "User"
+
+  # Method to call on controllers to get the current account
+  config.current_account_method = :current_account
+
+  # Method to call on controllers to get the current user
+  config.current_user_method = :current_user
+
+<% else -%>
+  # ==========================================================================
+  # Local Mode (default)
+  # ==========================================================================
+
+  # Multi-tenant mode is disabled by default.
+  # Set to true if you're building a SaaS platform with multiple accounts.
+  # config.multi_tenant = false
+
+  # Optional: Associate agents with users
+  # config.user_class = "User"
+  # config.current_user_method = :current_user
+
+<% end -%>
+  # ==========================================================================
+  # Sandbox Configuration
+  # ==========================================================================
+
+  # Sandbox service type for agent execution environments.
+  # Options: :local (Docker/Incus), :cloud_run, :kubernetes
+  config.sandbox_service = :local
+
+  # Custom sandbox limits (optional)
+  # config.sandbox_limits = {
+  #   max_runs: 10,
+  #   timeout_seconds: 300,
+  #   max_tokens: 50_000,
+  #   session_duration_minutes: 15
+  # }
+
+  # ==========================================================================
+  # UI Configuration
+  # ==========================================================================
+
+  # Use Inertia.js with React for the frontend (requires additional setup)
+  # config.use_inertia = false
+
+  # Custom layout for dashboard views
+  # config.layout = "application"
+
+  # ==========================================================================
+  # Storage Configuration
+  # ==========================================================================
+
+  # Storage service for screenshots and snapshots.
+  # Must respond to #signed_url_for(key, expires_in:) and #fetch_snapshot(key)
+  # config.storage_service = MyStorageService.new
+end

data/lib/generators/active_agent/dashboard/install/templates/migrations/create_active_agent_agent_runs.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+class CreateActiveAgentAgentRuns < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :active_agent_agent_runs do |t|
+      t.references :agent, null: false, foreign_key: { to_table: :active_agent_agents }
+
+      # Input
+      t.text :input_prompt
+      t.jsonb :input_params, default: {}
+
+      # Output
+      t.text :output
+      t.jsonb :output_metadata, default: {}
+
+      # Execution details
+      t.integer :status, default: 0, null: false
+      t.integer :duration_ms
+      t.datetime :started_at
+      t.datetime :completed_at
+
+      # Token usage
+      t.integer :input_tokens
+      t.integer :output_tokens
+      t.integer :total_tokens
+
+      # Error tracking
+      t.text :error_message
+      t.text :error_backtrace
+
+      # Trace for debugging
+      t.string :trace_id
+      t.jsonb :logs, default: []
+
+      t.timestamps
+    end
+
+    add_index :active_agent_agent_runs, :status
+    add_index :active_agent_agent_runs, :trace_id
+    add_index :active_agent_agent_runs, :created_at
+  end
+end

data/lib/generators/active_agent/dashboard/install/templates/migrations/create_active_agent_agent_templates.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+class CreateActiveAgentAgentTemplates < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :active_agent_agent_templates do |t|
+      t.string :name, null: false
+      t.string :slug, null: false
+      t.text :description
+      t.string :category
+
+      # Template configuration (same as agents)
+      t.string :provider, default: "openai"
+      t.string :model, default: "gpt-4o-mini"
+      t.text :instructions
+      t.string :preset_type
+      t.jsonb :appearance, default: {}
+      t.jsonb :instruction_sets, default: []
+      t.jsonb :tools, default: []
+      t.jsonb :mcp_servers, default: {}
+      t.jsonb :model_config, default: {}
+
+      # Metadata
+      t.string :icon
+      t.integer :usage_count, default: 0
+      t.boolean :featured, default: false
+      t.boolean :public, default: true
+      t.boolean :free_tier, default: true
+
+      t.timestamps
+    end
+
+    add_index :active_agent_agent_templates, :slug, unique: true
+    add_index :active_agent_agent_templates, :category
+    add_index :active_agent_agent_templates, :featured
+    add_index :active_agent_agent_templates, :usage_count
+    add_index :active_agent_agent_templates, :free_tier
+  end
+end

data/lib/generators/active_agent/dashboard/install/templates/migrations/create_active_agent_agent_versions.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+class CreateActiveAgentAgentVersions < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :active_agent_agent_versions do |t|
+      t.references :agent, null: false, foreign_key: { to_table: :active_agent_agents }
+
+      t.integer :version_number, null: false, default: 1
+      t.string :change_summary
+
+      # Snapshot of agent configuration at this version
+      t.jsonb :configuration_snapshot, null: false, default: {}
+
+      # Who made the change
+      t.string :created_by
+
+      t.timestamps
+    end
+
+    add_index :active_agent_agent_versions, [:agent_id, :version_number], unique: true
+  end
+end