actionagent 0.0.0 → 1.2.0

data/config/routes.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+ActionAgent::Engine.routes.draw do
+  # The React dashboard's entry point. Its own paths (/traces, /metrics,
+  # /agents/1/edit, ...) are matched by the catch-all at the bottom of this
+  # file, so deep links and the browser's back button both work wherever the
+  # engine is mounted.
+  root to: "dashboard#index"
+
+  # The server-rendered console. Same data, no JavaScript — useful when the
+  # bundle can't run, and the surface the dashboard shipped with before the
+  # React app moved into the engine.
+  scope :console do
+    resources :traces, only: [ :index, :show ], controller: "traces" do
+      collection do
+        get :metrics
+      end
+    end
+  end
+
+  # The dashboard's own JSON API, read and written by the React app.
+  namespace :api do
+    # Telemetry ingestion, relative to wherever the engine is mounted:
+    # <mount>/api/traces (e.g. /activeagents/api/traces at the default mount).
+    # Authenticated with a bearer token, not a session.
+    resources :traces, only: [ :create ]
+
+    # A JSON API has no :new or :edit forms to serve.
+    resources :agents, except: [ :new, :edit ] do
+      member do
+        get :versions
+        post :restore
+        get :runs
+        post :execute
+        post :test
+        post :duplicate
+        get :export
+        get :analytics
+      end
+      collection do
+        get :presets
+      end
+    end
+
+    resources :templates, only: [ :index, :show ] do
+      member do
+        post :use
+      end
+    end
+
+    resources :runs, controller: "agent_runs", only: [ :index, :show ] do
+      member do
+        post :cancel
+      end
+    end
+
+    # Sandboxes. The engine ships the in-memory backend; an operator registers
+    # real ones (see ActionAgent.sandbox_backends).
+    resources :sandboxes, param: :id, only: [ :index, :create, :show, :destroy ] do
+      collection do
+        post :compare
+      end
+      member do
+        post :run
+      end
+    end
+
+    # Tool inventory — auto-detected from the tool roster each generation
+    # request offered, telemetry tool spans, and solid_agent records.
+    resources :tools, only: [ :index ]
+
+    # MCP services — detected servers unioned with the default catalog
+    # (McpCatalog), plus on-demand sandbox provisioning. Keys are catalog
+    # slugs like "sequential-thinking", so the id segment allows dashes.
+    resources :mcp_servers, only: [ :index, :show ], id: /[^\/]+/ do
+      member do
+        post :launch
+      end
+    end
+
+    resources :instance_tiers, only: [ :index, :show ] do
+      collection do
+        get :recommend
+        get :pricing
+      end
+    end
+
+    resources :session_recordings, only: [ :index, :show, :destroy ] do
+      member do
+        get :actions
+        get "snapshot/:action_id", action: :snapshot, as: :snapshot
+        post :export
+        post :handoff
+        post :record_action
+        post :complete, action: :complete_session
+      end
+      collection do
+        get :recent
+        post :start_user_session
+      end
+    end
+
+    resource :analytics, only: [], controller: "analytics" do
+      get "/", action: :index
+    end
+
+    # Reading traces is the same path as ingesting them, separated by verb:
+    # POST is the SDK's authenticated-by-token ingest above, GET is the
+    # dashboard's session-authenticated read.
+    resources :traces, only: [ :index, :show ], controller: "trace_reports", as: :trace_reports
+    resource :metrics, only: [ :show ], controller: "metrics"
+
+    # Conversations (contexts, messages, generations) behind Interactions.
+    resources :interactions, only: [ :index, :show ]
+
+    # Agent output evaluations.
+    resources :evaluations, only: [ :index, :show, :create, :destroy ] do
+      member do
+        post :run
+      end
+    end
+
+    # Credentials: dashboard API keys (token shown once on create) and the
+    # owner's own LLM provider credentials, both encrypted at rest.
+    resources :api_keys, only: [ :index, :create, :destroy ]
+    resources :provider_keys, only: [ :index, :create, :destroy ], param: :provider
+
+    # Model catalogs for the agent builder (Ollama queried live from the
+    # configured host; hosted providers curated).
+    resources :provider_models, only: [ :index ]
+  end
+
+  # The account's agents presented as an authenticated MCP server (tools +
+  # agent:// resources) over Streamable HTTP JSON-RPC. Authenticated with a
+  # dashboard API key rather than a session, so it sits outside the api
+  # namespace's session-authenticated controllers.
+  post "mcp", to: "api/mcp#create"
+
+  # Everything else under the mount is a client-side route: render the
+  # dashboard and let the browser resolve it. Anchored last so it can only
+  # ever catch what the routes above did not, and refuses /api paths so a
+  # mistyped endpoint answers as an API would rather than returning a page.
+  get "*path", to: "dashboard#index", constraints: ->(request) { !request.path.include?("/api/") }
+end

data/lib/action_agent/compatibility.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+# Transitional aliases for the names this engine shipped under when it lived
+# inside the activeagent gem (<= 1.1.0).
+#
+# Three of these matter for more than tidiness:
+#
+#   * ActiveAgent::ProcessTelemetryTracesJob — Active Job serializes the class
+#     name into the queue payload, so a job enqueued before the upgrade is
+#     dequeued after it and must still resolve to something.
+#   * ActiveAgent::TelemetryTrace — apps subclass it (the activeagents.ai
+#     platform does) and it is referenced from initializers.
+#   * ActiveAgent::Dashboard — every existing initializer calls
+#     ActiveAgent::Dashboard.configure.
+#
+# Each warns once through the deprecator and forwards to the new constant.
+# Remove in the next major.
+module ActionAgent
+  module Compatibility
+    RENAMED = {
+      "Dashboard" => "ActionAgent",
+      "TelemetryTrace" => "ActionAgent::TelemetryTrace",
+      "ProcessTelemetryTracesJob" => "ActionAgent::ProcessTelemetryTracesJob"
+    }.freeze
+
+    # Installs const_missing on ActiveAgent so the old names keep resolving
+    # without eagerly loading the engine's models (which would drag Active
+    # Record in at boot, the very thing the gem split fixed).
+    def self.install!
+      return if @installed
+
+      ActiveAgent.singleton_class.prepend(ConstMissing)
+      @installed = true
+    end
+
+    module ConstMissing
+      def const_missing(name)
+        replacement = RENAMED[name.to_s]
+        return super unless replacement
+
+        ActionAgent.deprecator.warn(
+          "ActiveAgent::#{name} has moved to #{replacement}. " \
+          "The dashboard is now the actionagent gem; update your references."
+        )
+        replacement.constantize
+      end
+    end
+  end
+end

data/lib/action_agent/engine.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module ActionAgent
+  # Rails engine for the Active Agent dashboard: the agent builder, runs,
+  # conversations, evaluations, traces, metrics, sandboxes and session
+  # recordings, plus the trace ingest API and the MCP server facade.
+  #
+  # Mount it wherever you like:
+  #   mount ActionAgent::Engine => "/agents"
+  #
+  class Engine < ::Rails::Engine
+    isolate_namespace ActionAgent
+
+    engine_name "action_agent"
+
+    config.action_agent = ActiveSupport::OrderedOptions.new
+
+    # The dashboard's JS and CSS ship prebuilt in the gem. Adding the
+    # directory to the host app's asset paths is what lets a plain
+    # `mount ActionAgent::Engine` work without the host running a
+    # JavaScript build — or having a JavaScript build at all.
+    # Provider credentials and API keys are posted to the dashboard in the
+    # clear and encrypted at rest — filtering keeps them out of the request
+    # logs in between, where the gem would otherwise print them verbatim.
+    initializer "action_agent.filter_parameters" do |app|
+      app.config.filter_parameters += [ :credential, :api_key, :access_token ]
+    end
+
+    initializer "action_agent.assets", before: :append_assets_path do |app|
+      builds = root.join("app", "assets", "builds").to_s
+      next unless File.directory?(builds)
+
+      next unless app.config.respond_to?(:assets)
+
+      if app.config.assets.respond_to?(:paths)
+        app.config.assets.paths << builds unless app.config.assets.paths.include?(builds)
+      end
+
+      # Sprockets serves only what it was told to precompile, and the host's
+      # manifest.js cannot know about an engine's bundles. Without this the
+      # layout's stylesheet_link_tag/javascript_include_tag raise
+      # AssetNotPrecompiled in development and AssetNotFound in production —
+      # i.e. the dashboard's only page 500s on every sprockets-rails host.
+      # Propshaft serves everything on the load path and has no precompile
+      # list, so the respond_to? check is what distinguishes them.
+      if app.config.assets.respond_to?(:precompile)
+        app.config.assets.precompile |= %w[action_agent.js action_agent.css]
+      end
+    end
+  end
+end

data/lib/action_agent/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module ActionAgent
+  VERSION = "1.2.0"
+end

data/lib/action_agent.rb

@@ -0,0 +1,388 @@
+# frozen_string_literal: true
+
+module ActionAgent
+  class << self
+    # Table name prefix for the engine's models. The engine's own
+    # migrations create `active_agent_*` tables, so the default matches.
+    #
+    # A host app that already owns these tables under different names (the
+    # activeagents.ai platform grew them unprefixed) sets this to "" rather
+    # than renaming production tables. The engine's migrations read the same
+    # value, so the schema and the models never disagree.
+    #
+    # Defined before the engine is required on purpose: Rails' isolate_namespace
+    # installs its own table_name_prefix on an on_load(:active_record) hook
+    # unless the module already has one, and that hook would win over any
+    # definition made afterwards.
+    attr_writer :table_name_prefix
+
+    def table_name_prefix
+      global = defined?(::ActiveRecord::Base) ? ::ActiveRecord::Base.table_name_prefix : ""
+      "#{global}#{@table_name_prefix ||= "active_agent_"}"
+    end
+  end
+end
+
+# Both are hard requirements, and both must be loaded here rather than left to
+# the host app's Gemfile. Bundler.require only requires the gems an app lists
+# directly, so a transitive dependency is installed and activated but never
+# loaded:
+#
+#   * active_agent — Compatibility.install! below dereferences ::ActiveAgent at
+#     load time. An app whose Gemfile happens to list actionagent first (which
+#     RuboCop's Bundler/OrderedGems will produce, since it sorts before
+#     activeagent) would otherwise die at Bundler.require.
+#   * solid_agent — AgentExecutionService includes SolidAgent::HasContext in the
+#     agent class it builds for every run, so without this every Run fails with
+#     an uninitialized-constant error on any install that does not list the gem
+#     itself.
+require "active_agent"
+require "solid_agent"
+
+require "action_agent/version"
+require "action_agent/engine"
+require "action_agent/compatibility"
+
+# Dashboard engine for visualizing telemetry data and managing agents.
+#
+# Mount the engine in your routes to access the full dashboard:
+#
+#   # config/routes.rb
+#   mount ActionAgent::Engine => "/activeagents"
+#
+# The dashboard provides:
+# - Agent management: Create, edit, version, and execute agents
+# - Traces view: See all agent invocations with spans, timing, and token usage
+# - Metrics view: Aggregate statistics and charts
+# - Sandbox execution: Run agents in isolated environments
+# - Session recordings: Capture and replay browser sessions
+#
+# = Configuration Modes
+#
+# == Local Mode (default)
+# For self-hosted, single-tenant deployments:
+#
+#   ActionAgent.configure do |config|
+#     config.authentication_method = ->(controller) { controller.authenticate_admin! }
+#     config.sandbox_service = :local  # Docker/Incus
+#   end
+#
+# == Multi-tenant Mode
+# For SaaS platforms with multiple accounts:
+#
+#   ActionAgent.configure do |config|
+#     config.multi_tenant = true
+#     config.account_class = "Account"
+#     config.user_class = "User"
+#     config.current_account_method = :current_account
+#     config.current_user_method = :current_user
+#     config.authentication_method = ->(controller) { controller.authenticate_user! }
+#     config.sandbox_service = :cloud_run  # Managed
+#     config.use_inertia = true
+#   end
+#
+module ActionAgent
+  class << self
+    # Deprecation warnings for this gem, routed through Rails' machinery so a
+    # host app can silence or escalate them like any other.
+    def deprecator
+      @deprecator ||= ActiveSupport::Deprecation.new("2.0", "ActionAgent")
+    end
+
+    # Authentication method to call on controllers
+    # @return [Proc, nil] A proc that receives the controller instance
+    attr_accessor :authentication_method
+
+    # Enable multi-tenant mode (requires account association)
+    # @return [Boolean]
+    attr_accessor :multi_tenant
+
+    # Class name for the Account model (multi-tenant mode)
+    # @return [String, nil]
+    attr_accessor :account_class
+
+    # Class name for the User model
+    # @return [String, nil]
+    attr_accessor :user_class
+
+    # Method to call on controller to get current account (multi-tenant mode).
+    # Only usable when the host app has mixed that method into the engine's
+    # controllers; otherwise use current_account_resolver.
+    # @return [Symbol, nil]
+    attr_accessor :current_account_method
+
+    # Method to call on controller to get current user. Same caveat as
+    # current_account_method — see current_user_resolver.
+    # @return [Symbol, nil]
+    attr_accessor :current_user_method
+
+    # Resolves the signed-in user from the controller. Preferred over
+    # current_user_method: the engine's controllers are their own base
+    # class, so a host app's `current_user` helper is not on them unless
+    # the app deliberately put it there.
+    # @return [Proc, nil]
+    attr_accessor :current_user_resolver
+
+    # Resolves the current tenant from the controller. See
+    # current_user_resolver.
+    # @return [Proc, nil]
+    attr_accessor :current_account_resolver
+
+    # The tenant whose telemetry relates to +owner+. Traces belong to
+    # accounts while agents may belong to users, so the two are not always
+    # the same record and a host app says how to get from one to the other.
+    # @return [Proc, nil]
+    attr_accessor :tenant_resolver
+
+    # The agents an owner can reach. Defaults to the ones that owner owns.
+    # A host app where those differ — the platform's agents belong to users
+    # while its API keys belong to accounts — supplies its own scope.
+    # @return [Proc, nil]
+    attr_accessor :agent_scope_resolver
+
+    # Custom trace model class (for host app overrides)
+    # @return [String, nil]
+    attr_accessor :trace_model_class
+
+    # Enable React/Inertia frontend instead of ERB
+    # @return [Boolean]
+    attr_accessor :use_inertia
+
+    # Custom layout for the dashboard
+    # @return [String, nil]
+    attr_accessor :layout
+
+    # Sandbox service type (:local, :cloud_run, :kubernetes)
+    # @return [Symbol]
+    attr_accessor :sandbox_service
+
+    # Custom sandbox limits (overrides defaults)
+    # @return [Hash, nil]
+    attr_accessor :sandbox_limits
+
+    # Storage service for screenshots/snapshots
+    # @return [Object, nil] Object responding to #signed_url_for and #fetch_snapshot
+    attr_accessor :storage_service
+
+    # Bearer token required by the ingest API in single-tenant mode. When
+    # unset the local ingest endpoint accepts unauthenticated posts, so set
+    # it whenever the mount is reachable beyond your own machine.
+    # (Multi-tenant mode authenticates per-account keys instead.)
+    # @return [String, nil]
+    attr_accessor :ingest_api_key
+
+    # @deprecated Never consumed — dashboard controllers inherit
+    #   ActionController::Base. Retained as a no-op so existing
+    #   initializers that set it keep booting; remove in the next major.
+    # @return [String]
+    attr_accessor :base_controller_class
+
+    # Called before each run/trace-ingest to enforce host-app limits.
+    # Receives (owner, kind) where kind is :execution or :trace_ingest, and
+    # returns nil to allow, or to deny: a message String, or a Hash merged
+    # into the response so the app can surface its own usage numbers.
+    # Denials surface as HTTP 402 (execution) / 429 (ingest).
+    #
+    # Unset means unlimited, which is what a self-hosted install wants.
+    # @return [Proc, nil]
+    attr_accessor :quota_checker
+
+    # Resolves LLM provider credentials for a run. Receives
+    # (owner, provider_name) and returns a Hash merged into the agent's
+    # generation options (e.g. { access_token: "sk-..." } or
+    # { host: "http://localhost:11434" }), or nil to fall back to the
+    # host app's config/active_agent.yml.
+    #
+    # Unset means config/active_agent.yml is the only source, which is what
+    # a self-hosted install wants.
+    # @return [Proc, nil]
+    attr_accessor :provider_credentials_resolver
+
+    # Extra sandbox backends contributed by the host app, as
+    # { "cloud_run" => "CloudRunService" }. The engine ships :mock and
+    # :local (Docker); cloud backends live in the app that operates them.
+    # @return [Hash{String => String}]
+    attr_accessor :sandbox_backends
+
+    # Whether the dashboard may execute agents against real providers.
+    # Disable to run the dashboard as a read-only observability surface.
+    # @return [Boolean]
+    attr_accessor :execution_enabled
+
+    # Where the dashboard's upgrade CTAs should send people. Unset in a
+    # self-hosted install, where there is nothing to upgrade, and the CTAs
+    # say so instead of linking nowhere.
+    # @return [String, nil]
+    attr_accessor :upgrade_url
+
+    # Called after the dashboard performs a metered action, as
+    # (owner, kind) — the counterpart to quota_checker, for host apps that
+    # track usage against a plan. Unset means nothing is counted.
+    # @return [Proc, nil]
+    attr_accessor :usage_recorder
+
+    # Maps an ingested trace to the owner that its newly observed agents
+    # belong to. Defaults to the trace's account in multi-tenant mode and to
+    # nobody in single-tenant mode. A host app whose agents hang off a
+    # different record (the platform's hang off the account's owning user)
+    # supplies its own mapping.
+    # @return [Proc, nil]
+    attr_accessor :trace_owner_resolver
+
+    # How long telemetry traces are kept before TraceRetentionJob prunes
+    # them. A Duration applies to every trace; a callable receives each
+    # owner and returns that owner's window (nil keeps everything). Unset
+    # means nothing is ever deleted.
+    # @return [ActiveSupport::Duration, Proc, nil]
+    attr_accessor :trace_retention
+
+    # Whether API keys and provider credentials are encrypted at rest with
+    # Active Record Encryption. On by default, which requires the host app
+    # to have run `rails db:encryption:init`. Turning it off stores those
+    # secrets in plain text — a deliberate downgrade, never a default.
+    # @return [Boolean]
+    attr_accessor :encrypt_credentials
+
+    # Value stored in polymorphic *_type columns for dashboard agents
+    # (agent_memories.memorable_type, agent_contexts.contextable_type).
+    # Unset means the class name. A host app whose existing rows were
+    # written under its own constant sets its name here.
+    # @return [String, nil]
+    attr_accessor :agent_polymorphic_name
+
+    # Returns whether multi-tenant mode is enabled.
+    #
+    # @return [Boolean]
+    def multi_tenant?
+      @multi_tenant == true
+    end
+
+    # Returns whether agent execution is permitted.
+    #
+    # @return [Boolean]
+    def execution_enabled?
+      @execution_enabled != false
+    end
+
+    # Tells the host app that +owner+ performed +kind+. Never raises: a
+    # bookkeeping failure must not fail the action that was already taken.
+    def record_usage(owner, kind)
+      usage_recorder&.call(owner, kind)
+    rescue StandardError => e
+      Rails.logger.warn("[ActionAgent] usage recording failed: #{e.message}")
+      nil
+    end
+
+    # Asks the host app whether +owner+ may perform +kind+.
+    #
+    # @return [String, Hash, nil] denial message or payload, nil when allowed
+    def quota_denial(owner, kind)
+      return nil if quota_checker.nil?
+
+      quota_checker.call(owner, kind)
+    end
+
+    # Provider options for +owner+, or {} when the host app has none and
+    # config/active_agent.yml should be used as-is.
+    #
+    # @return [Hash]
+    def provider_credentials(owner, provider)
+      return {} if provider_credentials_resolver.nil?
+
+      provider_credentials_resolver.call(owner, provider) || {}
+    rescue StandardError => e
+      Rails.logger.warn("[ActionAgent] provider credential lookup failed: #{e.message}")
+      {}
+    end
+
+    # Returns the trace model class to use.
+    #
+    # @return [Class] The trace model class
+    def trace_model
+      if trace_model_class
+        trace_model_class.constantize
+      else
+        ActionAgent::TelemetryTrace
+      end
+    end
+
+    # The tenant +owner+ belongs to. Identity unless the host app says
+    # otherwise, which is right for every single-tenant install.
+    def tenant_for(owner)
+      return owner if tenant_resolver.nil?
+
+      tenant_resolver.call(owner)
+    end
+
+    # The agents +owner+ can reach.
+    #
+    # @return [ActiveRecord::Relation]
+    def agents_for(owner)
+      return agent_model.for_owner(owner) if agent_scope_resolver.nil?
+
+      agent_scope_resolver.call(owner) || agent_model.none
+    end
+
+    # Returns the agent model class to use.
+    #
+    # @return [Class] The agent model class
+    def agent_model
+      ActionAgent::Agent
+    end
+
+    # Returns the configured owner class: the Account in multi-tenant mode,
+    # the User otherwise. Nil when the host app configured neither, which
+    # is the single-user self-hosted case.
+    #
+    # @return [Class, nil]
+    def owner_class
+      name = multi_tenant? ? account_class : user_class
+      name&.safe_constantize
+    end
+
+    # Configures the dashboard.
+    #
+    # @yield [config] Configuration block
+    def configure
+      yield self
+    end
+
+    # Reset configuration to defaults
+    def reset!
+      @authentication_method = nil
+      @multi_tenant = false
+      @account_class = nil
+      @user_class = nil
+      @current_account_method = nil
+      @current_user_method = nil
+      @current_user_resolver = nil
+      @current_account_resolver = nil
+      @agent_scope_resolver = nil
+      @tenant_resolver = nil
+      @trace_model_class = nil
+      @use_inertia = false
+      @layout = nil
+      @sandbox_service = :local
+      @sandbox_limits = nil
+      @storage_service = nil
+      @ingest_api_key = nil
+      @base_controller_class = "ActionController::Base" # deprecated no-op
+      @quota_checker = nil
+      @provider_credentials_resolver = nil
+      @sandbox_backends = {}
+      @execution_enabled = true
+      @table_name_prefix = "active_agent_"
+      @agent_polymorphic_name = nil
+      @encrypt_credentials = true
+      @trace_retention = nil
+      @trace_owner_resolver = nil
+      @usage_recorder = nil
+      @upgrade_url = nil
+    end
+  end
+
+  # Set defaults
+  reset!
+end
+
+ActionAgent::Compatibility.install!

data/lib/actionagent.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+# The gem is `actionagent`; the code lives under `action_agent`. This is the
+# file Bundler requires when it sees `gem "actionagent"` — the same shim Rails
+# ships for activerecord, actionpack and friends.
+require "action_agent"