actionagent 0.0.0 → 1.2.0

data/lib/generators/action_agent/install_generator.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+
+module ActionAgent
+  # Generator for installing the ActiveAgent Dashboard.
+  #
+  # @example Run the generator
+  #   rails generate action_agent:install
+  #
+  # This will:
+  # - Create the telemetry_traces table migration
+  # - Add mount directive to routes
+  # - Create initializer for dashboard configuration
+  #
+  class InstallGenerator < Rails::Generators::Base
+    include ActiveRecord::Generators::Migration
+
+    source_root File.expand_path("templates", __dir__)
+
+    desc "Installs the ActiveAgent Dashboard with telemetry storage"
+
+    class_option :multi_tenant, type: :boolean, default: false,
+      desc: "Scope traces to an Account (adds account_id to the migration)"
+
+    class_option :skip_migrations, type: :boolean, default: false,
+      desc: "Skip copying the migrations"
+
+    class_option :traces_only, type: :boolean, default: false,
+      desc: "Install trace ingestion alone, without the agent/run/evaluation tables"
+
+    class_option :skip_routes, type: :boolean, default: false,
+      desc: "Skip adding the engine mount to routes.rb"
+
+    def copy_migrations
+      return if options[:skip_migrations]
+
+      # An app that installed the dashboard when it shipped inside activeagent
+      # already has this migration. Re-emitting it aborts the whole generator
+      # on a duplicate name, so upgrade that install in place instead: the
+      # table exists but predates agent attribution, and only agent_id is
+      # missing.
+      if existing_migration?("create_active_agent_telemetry_traces")
+        say_status :skip, "create_active_agent_telemetry_traces already exists", :yellow
+
+        unless existing_migration?("add_agent_id_to_active_agent_telemetry_traces")
+          migration_template(
+            "add_agent_id_to_active_agent_telemetry_traces.rb.erb",
+            "db/migrate/add_agent_id_to_active_agent_telemetry_traces.rb"
+          )
+        end
+      else
+        migration_template(
+          "create_active_agent_telemetry_traces.rb.erb",
+          "db/migrate/create_active_agent_telemetry_traces.rb"
+        )
+      end
+
+      # The rest of the dashboard — agents, runs, versions, conversations,
+      # evaluations, sandboxes, recordings, keys. Skippable for an app that
+      # only wants to be a trace sink.
+      return if options[:traces_only]
+
+      if existing_migration?("create_active_agent_dashboard_tables")
+        say_status :skip, "create_active_agent_dashboard_tables already exists", :yellow
+        return
+      end
+
+      migration_template(
+        "create_active_agent_dashboard_tables.rb.erb",
+        "db/migrate/create_active_agent_dashboard_tables.rb"
+      )
+    end
+
+    def add_route
+      return if options[:skip_routes]
+
+      # Rails' `route` action is only idempotent on an exact string match,
+      # so an app installed before the default path changed would get a
+      # second mount — and two unnamed mounts of the same engine raise
+      # "Invalid route name, already in use: 'active_agent'" at boot.
+      routes_file = File.join(destination_root, "config/routes.rb")
+      if File.exist?(routes_file) && File.read(routes_file).include?("ActionAgent::Engine")
+        say_status :skip, "engine already mounted in config/routes.rb", :yellow
+        return
+      end
+
+      route 'mount ActionAgent::Engine => "/activeagents"'
+    end
+
+    def create_initializer
+      template(
+        "action_agent.rb.erb",
+        "config/initializers/action_agent.rb"
+      )
+    end
+
+    def show_readme
+      say "\n"
+      say "ActiveAgent Dashboard installed successfully!", :green
+      say "\n"
+      say "Next steps:"
+      say "  1. Run migrations: rails db:migrate"
+      say "  2. Configure telemetry in config/active_agent.yml:"
+      say "     telemetry:"
+      say "       enabled: true"
+      say "       local_storage: true"
+      say "  3. Visit /activeagents to view the dashboard"
+      unless options[:traces_only]
+        say "\n"
+        say "The dashboard stores API keys and provider credentials encrypted."
+        say "Run `rails db:encryption:init` and add the keys to your credentials"
+        say "before creating any."
+      end
+      say "\n"
+    end
+
+    private
+
+    def migration_version
+      "[#{ActiveRecord::Migration.current_version}]"
+    end
+
+    # Whether db/migrate already carries a migration with this name. Checked
+    # against the filesystem rather than the database so the generator still
+    # works before the database exists.
+    def existing_migration?(name)
+      Dir.glob(File.join(destination_root.to_s, "db", "migrate", "*_#{name}.rb")).any?
+    end
+
+    # Consumed by the migration template.
+    def multi_tenant?
+      options[:multi_tenant]
+    end
+  end
+end

data/lib/generators/action_agent/templates/action_agent.rb.erb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+# ActiveAgent Dashboard Configuration
+#
+# This file configures the ActiveAgent telemetry dashboard.
+# The dashboard is mounted at /activeagents by default (see config/routes.rb).
+
+ActionAgent.configure do |config|
+  # ==========================================================================
+  # Authentication (required in production)
+  # ==========================================================================
+  #
+  # Provide a lambda that receives the controller and performs
+  # authentication. Return false or raise to deny access. Without one, the
+  # dashboard serves a 403 in production — traces contain prompts, outputs
+  # and error messages.
+  #
+  # Basic auth:
+  #   config.authentication_method = ->(controller) {
+  #     controller.authenticate_or_request_with_http_basic do |username, password|
+  #       username == "admin" && password == Rails.application.credentials.dashboard_password
+  #     end
+  #   }
+  #
+  # Devise:
+  #   config.authentication_method = ->(controller) {
+  #     controller.authenticate_admin!
+  #   }
+  #
+  # No authentication (development only!):
+  #   config.authentication_method = nil
+  #
+  config.authentication_method = nil
+
+  # ==========================================================================
+  # Ingest API authentication
+  # ==========================================================================
+  #
+  # Bearer token other apps must send when posting traces to the mounted
+  # ingest endpoint (/activeagents/api/traces). Leave unset only when the
+  # mount is not reachable beyond your own machine.
+  #
+  # config.ingest_api_key = Rails.application.credentials.dig(:active_agent, :ingest_api_key)
+
+  # ==========================================================================
+  # Multi-tenant mode (SaaS platforms only)
+  # ==========================================================================
+  #
+  # Scopes traces per account and authenticates ingest with per-account
+  # keys. Most self-hosted installs should leave this off.
+  #
+  # config.multi_tenant = true
+  # config.account_class = "Account"
+  # config.user_class = "User"
+  #
+  # How the engine finds the signed-in user and their account. These have to
+  # be resolvers rather than method names: the dashboard's controllers are
+  # their own base class, so your app's `current_user` helper is not on them.
+  # Read the session (or your auth library) directly — a resolver that calls
+  # back into `current_user` reaches the engine's own accessor, not yours.
+  #
+  # config.current_user_resolver = ->(controller) {
+  #   User.find_by(id: controller.session[:user_id])
+  # }
+  # config.current_account_resolver = ->(controller) {
+  #   controller.send(:current_user)&.account
+  # }
+  #
+  # With an owner model configured, an owner that does not resolve sees
+  # nothing rather than everything. An empty dashboard for a signed-in user
+  # means the resolver above returned nil.
+
+  # ==========================================================================
+  # UI
+  # ==========================================================================
+  #
+  # Custom layout for dashboard views (the default layout loads Tailwind,
+  # Turbo and Stimulus from CDNs — override for CSP-strict or air-gapped
+  # environments).
+  #
+  # config.layout = "application"
+end

data/lib/generators/action_agent/templates/add_agent_id_to_active_agent_telemetry_traces.rb.erb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+# Tops up a telemetry_traces table created before traces carried an agent
+# attribution. Emitted instead of the create-table migration when the install
+# generator finds one already in db/migrate.
+#
+# Without agent_id, AgentRegistrar cannot attribute an ingested trace to a
+# dashboard agent: auto-registration silently does nothing, and the dashboard
+# home page fails as soon as the first agent exists.
+class AddAgentIdToActiveAgentTelemetryTraces < ActiveRecord::Migration<%= migration_version %>
+  def up
+    return unless table_exists?(:active_agent_telemetry_traces)
+    return if column_exists?(:active_agent_telemetry_traces, :agent_id)
+
+    add_column :active_agent_telemetry_traces, :agent_id, :bigint
+    add_index :active_agent_telemetry_traces, :agent_id
+  end
+
+  def down
+    return unless column_exists?(:active_agent_telemetry_traces, :agent_id)
+
+    remove_column :active_agent_telemetry_traces, :agent_id
+  end
+end

data/lib/generators/action_agent/templates/create_active_agent_dashboard_tables.rb.erb

@@ -0,0 +1,319 @@
+# frozen_string_literal: true
+
+# Creates every table the ActiveAgent Dashboard reads and writes, apart from
+# active_agent_telemetry_traces (which ships separately so an app can install
+# trace ingestion alone).
+#
+# Table names follow ActionAgent.table_name_prefix, so an app that
+# has deliberately set the prefix to "" gets unprefixed tables and one that
+# leaves the default gets active_agent_*.
+#
+# JSON columns are jsonb on PostgreSQL and json elsewhere: the dashboard runs
+# on SQLite and MySQL, it just loses jsonb containment (see
+# ActionAgent::Agent.with_tool, which falls back to a LIKE).
+class CreateActiveAgentDashboardTables < ActiveRecord::Migration<%= migration_version %>
+  def change
+    prefix = ActionAgent.table_name_prefix
+
+    create_table "#{prefix}agents" do |t|
+      t.string :name, null: false
+      t.string :slug, null: false
+      t.text :description
+      t.string :provider, default: "openai"
+      t.string :model, default: "gpt-4o-mini"
+      t.text :instructions
+      t.string :preset_type
+      t.string :agent_class_name
+      t.string :action_name
+      t.integer :status, default: 0, null: false
+      t.column :appearance, json_type, default: {}
+      t.column :instruction_sets, json_type, default: []
+      t.column :tools, json_type, default: []
+      t.column :mcp_servers, json_type, default: []
+      t.column :model_config, json_type, default: {}
+      t.column :response_format, json_type, default: {}
+      t.column :action_prompts, json_type, default: [], null: false
+
+      # Agents discovered from reported telemetry rather than authored here.
+      t.string :service_name
+      t.string :source
+      t.datetime :first_observed_at
+      t.datetime :last_observed_at
+
+      t.bigint :user_id
+      t.bigint :account_id
+      t.timestamps
+      t.index :user_id
+      t.index :account_id
+      t.index [ :user_id, :slug ], unique: true
+      t.index :status
+    end
+
+    create_table "#{prefix}agent_versions" do |t|
+      t.bigint :agent_id, null: false
+      t.integer :version_number, default: 1, null: false
+      t.column :configuration_snapshot, json_type, default: {}, null: false
+      t.string :change_summary
+      t.string :created_by
+      t.timestamps
+      t.index [ :agent_id, :version_number ], unique: true
+    end
+
+    create_table "#{prefix}agent_runs" do |t|
+      t.bigint :agent_id, null: false
+      t.string :trace_id
+      t.string :action_name
+      t.integer :status, default: 0, null: false
+      t.text :input_prompt
+      t.column :input_params, json_type, default: {}
+      t.text :output
+      t.column :output_metadata, json_type, default: {}
+      t.column :logs, json_type, default: []
+      t.text :error_message
+      t.text :error_backtrace
+      t.integer :input_tokens
+      t.integer :output_tokens
+      t.integer :total_tokens
+      t.integer :duration_ms
+      t.datetime :started_at
+      t.datetime :completed_at
+      t.timestamps
+      t.index :agent_id
+      t.index :trace_id
+      t.index :created_at
+    end
+
+    create_table "#{prefix}agent_templates" do |t|
+      t.string :name, null: false
+      t.string :slug, null: false
+      t.text :description
+      t.string :category
+      t.string :icon
+      t.string :provider, default: "openai"
+      t.string :model, default: "gpt-4o-mini"
+      t.text :instructions
+      t.string :preset_type
+      t.column :appearance, json_type, default: {}
+      t.column :instruction_sets, json_type, default: []
+      t.column :tools, json_type, default: []
+      t.column :mcp_servers, json_type, default: {}
+      t.column :model_config, json_type, default: {}
+      t.boolean :featured, default: false
+      t.boolean :free_tier, default: false
+      t.boolean :public, default: true
+      t.integer :usage_count, default: 0
+      t.timestamps
+      t.index :slug, unique: true
+    end
+
+    # Conversation persistence — the solid_agent schema, owned by the engine
+    # so the dashboard's Interactions view works without that gem installed.
+    create_table "#{prefix}agent_contexts" do |t|
+      t.string :agent_name, null: false
+      t.string :action_name, null: false
+      t.string :contextable_type
+      t.bigint :contextable_id
+      t.text :instructions
+      t.column :options, json_type, default: {}
+      t.string :trace_id
+      t.integer :total_input_tokens, default: 0
+      t.integer :total_output_tokens, default: 0
+      t.timestamps
+      t.index [ :contextable_type, :contextable_id ]
+      t.index :trace_id
+    end
+
+    create_table "#{prefix}agent_messages" do |t|
+      t.bigint :agent_context_id, null: false
+      t.string :role, null: false
+      t.text :content
+      t.string :content_checksum
+      t.string :tool_call_id
+      t.string :tool_name
+      t.column :tool_arguments, json_type, default: {}
+      t.column :tool_result, json_type
+      t.column :attachments, json_type, default: []
+      t.column :metadata, json_type, default: {}
+      t.column :provenance, json_type, default: {}
+      t.timestamps
+      t.index :agent_context_id
+    end
+
+    create_table "#{prefix}agent_generations" do |t|
+      t.bigint :agent_context_id, null: false
+      t.text :content
+      t.string :model
+      t.string :provider
+      t.string :finish_reason
+      t.integer :input_tokens, default: 0
+      t.integer :output_tokens, default: 0
+      t.integer :cached_tokens, default: 0
+      t.integer :reasoning_tokens, default: 0
+      t.float :duration_seconds
+      t.column :tool_calls, json_type, default: []
+      t.column :raw_response, json_type
+      t.column :provenance, json_type, default: {}
+      t.string :trace_id
+      t.timestamps
+      t.index :agent_context_id
+      t.index :trace_id
+    end
+
+    create_table "#{prefix}agent_memories" do |t|
+      t.string :memorable_type
+      t.bigint :memorable_id
+      t.string :scope, default: "default", null: false
+      t.timestamps
+      t.index [ :memorable_type, :memorable_id, :scope ], unique: true,
+        name: "index_active_agent_memories_on_memorable_and_scope"
+    end
+
+    create_table "#{prefix}agent_memory_entries" do |t|
+      t.bigint :agent_memory_id, null: false
+      t.text :content, null: false
+      t.string :source_agent
+      t.string :category
+      t.timestamps
+      t.index :agent_memory_id
+    end
+
+    create_table "#{prefix}evaluations" do |t|
+      t.bigint :agent_id, null: false
+      t.string :name, null: false
+      t.string :judge_kind, default: "rules", null: false
+      t.string :judge_model
+      t.integer :sample_size, default: 20, null: false
+      t.column :criteria, json_type, default: [], null: false
+      t.column :config, json_type, default: {}, null: false
+      t.timestamps
+      t.index [ :agent_id, :name ], unique: true
+    end
+
+    create_table "#{prefix}evaluation_runs" do |t|
+      t.bigint :evaluation_id, null: false
+      t.integer :status, default: 0, null: false
+      t.column :scores, json_type, default: {}
+      t.integer :samples_evaluated, default: 0
+      t.integer :samples_passed, default: 0
+      t.text :error_message
+      t.datetime :completed_at
+      t.timestamps
+      t.index :evaluation_id
+    end
+
+    create_table "#{prefix}sandbox_sessions" do |t|
+      t.string :session_id, null: false
+      t.bigint :agent_template_id
+      t.integer :status, default: 0
+      t.string :sandbox_type, default: "playwright_mcp"
+      t.string :cloud_run_job_id
+      t.string :cloud_run_url
+      t.column :runs, json_type, default: []
+      # MCP servers this session was started with, so the MCP Services view
+      # can show a launched server as running rather than offering to start
+      # a second copy.
+      t.column :mcp_servers, json_type, default: []
+      t.integer :runs_count, default: 0
+      t.integer :max_runs, default: 10
+      t.integer :timeout_seconds, default: 300
+      t.integer :total_duration_ms, default: 0
+      t.integer :total_tokens, default: 0
+      t.text :error_message
+      t.datetime :expires_at
+      t.datetime :last_activity_at
+      t.bigint :user_id
+      t.bigint :account_id
+      t.timestamps
+      t.index :session_id, unique: true
+      t.index :user_id
+    end
+
+    create_table "#{prefix}sandbox_runs" do |t|
+      t.bigint :sandbox_session_id
+      t.text :task, null: false
+      t.integer :status, default: 0, null: false
+      t.text :result
+      t.text :error
+      t.column :screenshots, json_type, default: []
+      t.integer :tokens_used, default: 0
+      t.integer :duration_ms
+      t.datetime :started_at
+      t.datetime :completed_at
+      t.timestamps
+      t.index :sandbox_session_id
+    end
+
+    create_table "#{prefix}session_recordings" do |t|
+      t.string :name
+      t.bigint :agent_run_id
+      t.bigint :sandbox_session_id
+      t.integer :status, default: 0, null: false
+      t.integer :action_count, default: 0
+      t.integer :duration_ms
+      t.column :metadata, json_type, default: {}
+      t.bigint :user_id
+      t.bigint :account_id
+      t.timestamps
+      t.index :agent_run_id
+      t.index :sandbox_session_id
+      t.index :user_id
+      t.index :account_id
+    end
+
+    create_table "#{prefix}recording_actions" do |t|
+      t.bigint :session_recording_id, null: false
+      t.integer :sequence, null: false
+      t.string :action_type, null: false
+      t.string :selector
+      t.text :value
+      t.integer :timestamp_ms, null: false
+      t.string :screenshot_key
+      t.string :dom_snapshot_key
+      t.column :metadata, json_type, default: {}
+      t.timestamps
+      t.index [ :session_recording_id, :sequence ], unique: true,
+        name: "index_active_agent_recording_actions_on_recording_and_sequence"
+    end
+
+    create_table "#{prefix}recording_snapshots" do |t|
+      t.bigint :session_recording_id, null: false
+      t.bigint :recording_action_id
+      t.string :snapshot_type, null: false
+      t.string :storage_key, null: false
+      t.integer :width
+      t.integer :height
+      t.integer :file_size_bytes
+      t.timestamps
+      t.index :session_recording_id
+      t.index :recording_action_id
+    end
+
+    create_table "#{prefix}api_keys" do |t|
+      t.string :name, null: false
+      t.string :token, null: false
+      t.string :token_prefix, null: false
+      t.datetime :last_used_at
+      t.bigint :user_id
+      t.bigint :account_id
+      t.timestamps
+      t.index :token, unique: true
+    end
+
+    create_table "#{prefix}provider_keys" do |t|
+      t.string :provider, null: false
+      t.string :credential, null: false
+      t.bigint :user_id
+      t.bigint :account_id
+      t.timestamps
+      t.index [ :account_id, :provider ]
+      t.index [ :user_id, :provider ]
+    end
+  end
+
+  private
+
+  # jsonb where the adapter has it, json where it doesn't.
+  def json_type
+    @json_type ||= connection.adapter_name.to_s.downcase.include?("postgres") ? :jsonb : :json
+  end
+end

data/lib/generators/action_agent/templates/create_active_agent_telemetry_traces.rb.erb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+class CreateActiveAgentTelemetryTraces < ActiveRecord::Migration<%= migration_version %>
+  def change
+    create_table :active_agent_telemetry_traces do |t|
+<% if multi_tenant? -%>
+      # Multi-tenant mode: every query is scoped through `for_account`, and
+      # ingest authenticates a per-account key. The foreign key requires an
+      # existing `accounts` table — on PostgreSQL/MySQL this migration must
+      # run after the one that creates it (drop `foreign_key: true` if your
+      # tenant table is named differently).
+      t.references :account, null: false, foreign_key: true
+<% end -%>
+      t.string :trace_id, null: false
+      t.string :service_name
+      t.string :environment
+      t.datetime :timestamp, index: true
+      t.column :spans, json_type, default: []
+      t.column :resource_attributes, json_type, default: {}
+      t.column :sdk_info, json_type, default: {}
+      t.decimal :total_duration_ms, precision: 12, scale: 3
+      t.integer :total_input_tokens, default: 0
+      t.integer :total_output_tokens, default: 0
+      t.integer :total_thinking_tokens, default: 0
+      t.string :status
+      t.string :agent_class, index: true
+      t.string :agent_action
+      # Set on ingest when the trace can be attributed to a dashboard agent;
+      # nullable because a trace must still land when it cannot be.
+      t.bigint :agent_id, index: true
+      t.text :error_message
+
+      t.timestamps
+    end
+
+<% if multi_tenant? -%>
+    # Ingest dedupes on trace_id (per account when multi-tenant); the unique
+    # index makes that dedupe race-proof rather than check-then-insert.
+    add_index :active_agent_telemetry_traces, [:account_id, :trace_id], unique: true
+    add_index :active_agent_telemetry_traces, [:account_id, :timestamp]
+<% else -%>
+    add_index :active_agent_telemetry_traces, :trace_id, unique: true
+<% end -%>
+    add_index :active_agent_telemetry_traces, :status
+    add_index :active_agent_telemetry_traces, [:agent_class, :agent_action]
+    add_index :active_agent_telemetry_traces, [:service_name, :environment]
+    add_index :active_agent_telemetry_traces, :created_at
+  end
+
+  private
+
+  # jsonb where the adapter has it, json where it doesn't. The dashboard
+  # traverses spans in SQL on PostgreSQL, and jsonb_array_elements rejects a
+  # json argument, so the column type and the query have to agree.
+  def json_type
+    @json_type ||= connection.adapter_name.to_s.downcase.include?("postgres") ? :jsonb : :json
+  end
+end