actionagent 0.0.0 → 1.2.0

data/app/controllers/action_agent/api/traces_controller.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+module ActionAgent
+  module Api
+    # Telemetry ingestion endpoint.
+    #
+    # Receives traces from ActiveAgent::Telemetry::Reporter and stores them
+    # for analysis and visualization in the dashboard.
+    #
+    # Supports two modes:
+    # - Local mode: synchronous processing; unauthenticated unless
+    #   ActionAgent.ingest_api_key is set (set it whenever the
+    #   mount is reachable beyond your own machine)
+    # - Multi-tenant mode: per-account Bearer token auth, async processing
+    #   via job
+    #
+    # @example Local mode request
+    #   POST <mount>/api/traces  (e.g. /activeagents/api/traces)
+    #   Content-Type: application/json
+    #
+    #   {
+    #     "traces": [...],
+    #     "sdk": { "name": "activeagent", "version": "0.5.0" }
+    #   }
+    #
+    # @example Multi-tenant mode request
+    #   POST <mount>/api/traces  (e.g. /activeagents/api/traces)
+    #   Authorization: Bearer <api_key>
+    #   Content-Type: application/json
+    #
+    #   {
+    #     "traces": [...],
+    #     "sdk": { "name": "activeagent", "version": "0.5.0" }
+    #   }
+    #
+    class TracesController < ActionController::API
+      before_action :authenticate_api_key!, if: -> { ActionAgent.multi_tenant? }
+      before_action :authenticate_ingest_key!, unless: -> { ActionAgent.multi_tenant? }
+
+      # Maximum traces accepted per request (mirrors
+      # ProcessTelemetryTracesJob::MAX_TRACES_PER_JOB).
+      MAX_TRACES_PER_REQUEST = 100
+
+      # POST <mount>/api/traces  (e.g. /activeagents/api/traces)
+      def create
+        traces = Array(params[:traces]).take(MAX_TRACES_PER_REQUEST)
+        sdk_info = params[:sdk] || {}
+
+        return head :accepted if traces.empty?
+
+        if ActionAgent.multi_tenant?
+          # Multi-tenant mode: process in background
+          ActionAgent::ProcessTelemetryTracesJob.perform_later(
+            account_id: @account&.id,
+            traces: traces.as_json,
+            sdk_info: sdk_info.as_json,
+            received_at: Time.current.iso8601(6)
+          )
+        else
+          # Local mode: process synchronously
+          process_traces_synchronously(traces, sdk_info)
+        end
+
+        head :accepted
+      rescue ActionController::ParameterMissing => e
+        render json: { error: e.message }, status: :bad_request
+      rescue StandardError => e
+        Rails.logger.error("[ActionAgent] Trace ingestion error: #{e.message}")
+        render json: { error: "Internal server error" }, status: :internal_server_error
+      end
+
+      private
+
+      # Authenticates the request using Bearer token from Authorization header.
+      # Only used in multi-tenant mode.
+      def authenticate_api_key!
+        token = extract_bearer_token
+
+        if token.blank?
+          render json: { error: "Missing Authorization header" }, status: :unauthorized
+          return
+        end
+
+        account_class = ActionAgent.account_class.constantize
+        @account = account_class.find_by(telemetry_api_key: token)
+
+        if @account.nil?
+          render json: { error: "Invalid API key" }, status: :unauthorized
+          return
+        end
+
+        # Track usage for rate limiting (if the account responds to it)
+        @account.increment_telemetry_usage! if @account.respond_to?(:increment_telemetry_usage!)
+      end
+
+      # Requires the configured single-tenant ingest key when one is set.
+      # The telemetry reporter and ruby_llm_telemetry both send their
+      # api_key as a Bearer header, so remote apps work unchanged.
+      def authenticate_ingest_key!
+        expected = ActionAgent.ingest_api_key
+        return if expected.blank?
+
+        token = extract_bearer_token
+        return if token.present? && ActiveSupport::SecurityUtils.secure_compare(token, expected)
+
+        render json: { error: "Invalid API key" }, status: :unauthorized
+      end
+
+      # Extracts Bearer token from Authorization header.
+      def extract_bearer_token
+        auth_header = request.headers["Authorization"]
+        return nil if auth_header.blank?
+
+        match = auth_header.match(/^Bearer\s+(.+)$/i)
+        match[1] if match
+      end
+
+      # Process traces synchronously for local development.
+      def process_traces_synchronously(traces, sdk_info)
+        model = ActionAgent.trace_model
+
+        traces.each do |trace|
+          # Skip if trace already exists (idempotency)
+          next if model.exists?(trace_id: trace["trace_id"])
+
+          model.create_from_payload(trace, sdk_info)
+        rescue StandardError => e
+          Rails.logger.error(
+            "[ActionAgent] Failed to process trace #{trace['trace_id']}: " \
+            "#{e.class} - #{e.message}"
+          )
+        end
+      end
+    end
+  end
+end

data/app/controllers/action_agent/application_controller.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module ActionAgent
+  # Base controller for the ActiveAgent Dashboard.
+  #
+  # Handles authentication and provides helper methods for multi-tenant mode.
+  class ApplicationController < ActionController::Base
+    protect_from_forgery with: :exception
+
+    before_action :authenticate_dashboard!
+
+    # Use custom layout if configured, otherwise use engine layout
+    layout -> { ActionAgent.layout || "action_agent/application" }
+
+    helper_method :current_user, :current_owner
+
+    # Opts an action out of the host app's authentication — for the handful
+    # of endpoints that are deliberately public (the template gallery, the
+    # demo sandbox). Mirrors the Rails 8 authentication generator's helper
+    # so controllers read the same either side of the extraction.
+    def self.allow_unauthenticated_access(**options)
+      skip_before_action :authenticate_dashboard!, **options
+    end
+
+    private
+
+    def authenticate_dashboard!
+      if ActionAgent.authentication_method.nil?
+        # Traces contain prompts, outputs, and error backtraces. Refuse to
+        # serve them unauthenticated anywhere but a local development or
+        # test environment — a staging or review-app deployment runs under
+        # its own RAILS_ENV and is just as reachable as production.
+        unless Rails.env.local?
+          render plain: "ActiveAgent Dashboard: set ActionAgent.authentication_method " \
+            "(see docs/framework/dashboard.md) to enable access in production.",
+            status: :forbidden
+        end
+        return
+      end
+
+      result = ActionAgent.authentication_method.call(self)
+      head :unauthorized unless result
+    rescue StandardError => e
+      Rails.logger.error("[ActionAgent] Authentication error: #{e.message}")
+      head :unauthorized
+    end
+
+    # Returns the current user from the host application.
+    def current_user
+      return @current_user if defined?(@current_user)
+
+      @current_user = resolve_actor(
+        ActionAgent.current_user_resolver,
+        ActionAgent.current_user_method,
+        :current_user
+      )
+    end
+
+    # Returns the current owner (account in multi-tenant, user otherwise).
+    def current_owner
+      # No fallback to the user in multi-tenant mode: a signed-in user with
+      # no tenant owns nothing here, and quietly substituting them would
+      # hand them a scope they are not part of.
+      if ActionAgent.multi_tenant?
+        resolve_actor(
+          ActionAgent.current_account_resolver,
+          ActionAgent.current_account_method,
+          :current_owner
+        )
+      else
+        current_user
+      end
+    end
+
+    # Prefers the host app's lambda. A named method is only called when the
+    # controller really responds to it and it isn't the accessor we are
+    # already inside — configuring current_user_method = :current_user is
+    # the obvious thing to write, and it would otherwise recurse forever.
+    #
+    # The re-entrancy guard covers the same mistake in lambda form. The
+    # engine's controllers are their own base class, so the natural-looking
+    # `->(c) { c.current_user }` resolves to *this* method rather than the
+    # host app's, and without the guard it recurses until SystemStackError.
+    # Degrading to nil turns a 500 into an unresolved owner, which now
+    # scopes to nothing rather than to everything.
+    def resolve_actor(resolver, method_name, own_name)
+      @resolving_actors ||= {}
+      return nil if @resolving_actors[own_name]
+
+      @resolving_actors[own_name] = true
+      begin
+        return resolver.call(self) if resolver
+
+        return nil if method_name.nil? || method_name.to_sym == own_name
+        return nil unless respond_to?(method_name, true)
+
+        send(method_name)
+      ensure
+        @resolving_actors[own_name] = false
+      end
+    rescue NoMethodError
+      nil
+    end
+  end
+end

data/app/controllers/action_agent/dashboard_controller.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module ActionAgent
+  # Serves the React dashboard.
+  #
+  # Every path under the mount renders this one action; routing below it
+  # happens in the browser. Initial state is handed over as a JSON data
+  # attribute rather than through Inertia, so the engine works in any host
+  # app without adding a frontend framework to it.
+  class DashboardController < ApplicationController
+    # The React dashboard brings its own chrome, so it does not use the
+    # server-rendered layout the traces views share.
+    layout -> { ActionAgent.layout || "action_agent/react" }
+
+    def index
+      render "action_agent/dashboard/index", locals: { props: props }
+    end
+
+    private
+
+    def props
+      {
+        user: current_user_props,
+        account: current_account_props,
+        initialAgents: serialize_agents(owner_agents.order(updated_at: :desc).limit(20)),
+        meta: meta_props,
+        mountPath: active_agent_dashboard_mount_path,
+        # Billing is the host app's business; the dashboard renders no
+        # subscription chrome unless it is told about one.
+        subscription: nil
+      }
+    end
+
+    def owner_agents
+      ActionAgent.agents_for(current_owner)
+    end
+
+    def meta_props
+      {
+        activeagentVersion: ActiveAgent::VERSION,
+        providers: Agent::PROVIDERS,
+        presetTypes: Agent::PRESET_TYPES,
+        instructionSets: Agent::INSTRUCTION_SETS,
+        availableTools: Agent::AVAILABLE_TOOLS,
+        executionEnabled: ActionAgent.execution_enabled?,
+        multiTenant: ActionAgent.multi_tenant?,
+        upgradeUrl: ActionAgent.upgrade_url
+      }
+    end
+
+    def serialize_agents(agents)
+      agents = agents.to_a
+      scorecards = AgentScorecard.for_agents(agents)
+
+      agents.map do |agent|
+        {
+          id: agent.id,
+          name: agent.name,
+          slug: agent.slug,
+          description: agent.description,
+          provider: agent.provider,
+          model: agent.model,
+          status: agent.status,
+          presetType: agent.preset_type,
+          appearance: agent.appearance,
+          versionCount: agent.version_count,
+          createdAt: agent.created_at,
+          updatedAt: agent.updated_at,
+          stats: scorecards[agent.id]
+        }
+      end
+    rescue ActiveRecord::StatementInvalid
+      # Telemetry-only installs have the traces table but not the rest of
+      # the dashboard schema; the app still boots and shows an empty list.
+      []
+    end
+
+    def current_user_props
+      return { name: "Guest" } unless current_user
+
+      {
+        id: current_user.id,
+        name: current_user.try(:display_name) || current_user.try(:name) || current_user.try(:email_address),
+        email: current_user.try(:email_address) || current_user.try(:email)
+      }
+    end
+
+    def current_account_props
+      return nil unless current_owner
+
+      {
+        id: current_owner.id,
+        name: current_owner.try(:name),
+        telemetry_api_key: current_owner.try(:telemetry_api_key)
+      }
+    end
+
+    # Where the engine is mounted, so the React app can build API URLs
+    # without assuming a path.
+    def active_agent_dashboard_mount_path
+      request.script_name.presence || "/"
+    end
+  end
+end

data/app/controllers/action_agent/traces_controller.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module ActionAgent
+  # Controller for viewing telemetry traces.
+  #
+  # Provides:
+  # - List view with filtering and pagination
+  # - Detail view with span timeline
+  # - Metrics overview
+  # - Live updates via Turbo Streams
+  class TracesController < ApplicationController
+    def index
+      @traces = fetch_traces
+      @metrics = calculate_metrics
+
+      respond_to do |format|
+        format.html
+        # turbo-rails is optional; responding to an unregistered MIME
+        # type raises in host apps without it.
+        format.turbo_stream if turbo_stream_available?
+      end
+    end
+
+    def show
+      @trace = scoped_traces.find(params[:id])
+    end
+
+    def metrics
+      @metrics = calculate_metrics
+      @agent_stats = agent_statistics
+      @time_series = time_series_data
+
+      respond_to do |format|
+        format.html
+        format.turbo_stream if turbo_stream_available?
+      end
+    end
+
+    private
+
+    def turbo_stream_available?
+      Mime::Type.lookup_by_extension(:turbo_stream).present?
+    end
+
+    # All queries honor the configured trace model and, in multi-tenant
+    # mode, the current owner's account (for_account no-ops otherwise).
+    #
+    # In multi-tenant mode an unresolvable owner returns nothing rather
+    # than falling through: current_owner degrades to current_user when
+    # current_account_method is unset, which would scope by a user id
+    # against account_id — another tenant's traces.
+    def scoped_traces
+      model = ActionAgent.trace_model
+      return model.none if ActionAgent.multi_tenant? && current_owner.nil?
+
+      model.for_account(current_owner)
+    end
+
+    def fetch_traces
+      traces = scoped_traces.recent
+
+      traces = traces.for_agent(params[:agent]) if params[:agent].present?
+      traces = traces.with_errors if params[:status] == "error"
+      traces = traces.for_service(params[:service]) if params[:service].present?
+
+      if params[:start_date].present? && params[:end_date].present?
+        traces = traces.for_date_range(
+          Time.parse(params[:start_date]),
+          Time.parse(params[:end_date])
+        )
+      end
+
+      traces.limit(params[:limit] || 50)
+    end
+
+    def calculate_metrics
+      traces = scoped_traces.where(
+        "created_at > ?", 24.hours.ago
+      )
+
+      {
+        total_traces: traces.count,
+        total_tokens: traces.sum(:total_input_tokens) + traces.sum(:total_output_tokens),
+        avg_duration_ms: traces.average(:total_duration_ms)&.round(2) || 0,
+        error_rate: calculate_error_rate(traces),
+        unique_agents: traces.distinct.count(:agent_class)
+      }
+    end
+
+    def calculate_error_rate(traces)
+      total = traces.count
+      return 0.0 if total.zero?
+
+      errors = traces.with_errors.count
+      ((errors.to_f / total) * 100).round(2)
+    end
+
+    def agent_statistics
+      scoped_traces
+        .where("created_at > ?", 24.hours.ago)
+        .group(:agent_class)
+        .select(
+          "agent_class",
+          "COUNT(*) as trace_count",
+          "SUM(total_input_tokens + total_output_tokens) as total_tokens",
+          "AVG(total_duration_ms) as avg_duration",
+          "SUM(CASE WHEN status = 'ERROR' THEN 1 ELSE 0 END) as error_count"
+        )
+    end
+
+    def time_series_data
+      scoped_traces
+        .where("created_at > ?", 1.hour.ago)
+        .group_by_minute(:created_at)
+        .count
+    rescue NoMethodError
+      # Fallback if groupdate gem not available
+      {}
+    end
+  end
+end

data/app/jobs/action_agent/agent_execution_job.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module ActionAgent
+  class AgentExecutionJob < ApplicationJob
+    queue_as :agents
+
+    def perform(run_id)
+      run = AgentRun.find(run_id)
+      return if run.cancelled? || run.complete?
+
+      run.update!(status: :running, started_at: Time.current)
+      run.add_log("Starting execution", level: :info)
+
+      begin
+        agent_record = run.agent
+
+        # Build the agent class dynamically based on configuration
+        result = execute_agent(agent_record, run)
+
+        run.update!(
+          output: result[:output],
+          output_metadata: result[:metadata],
+          status: :complete,
+          completed_at: Time.current,
+          duration_ms: ((Time.current - run.started_at) * 1000).to_i,
+          input_tokens: result.dig(:usage, :input_tokens),
+          output_tokens: result.dig(:usage, :output_tokens),
+          total_tokens: result.dig(:usage, :total_tokens)
+        )
+        run.add_log("Execution completed successfully", level: :info)
+
+      rescue => e
+        run.update!(
+          status: :failed,
+          completed_at: Time.current,
+          error_message: e.message,
+          error_backtrace: e.backtrace&.first(10)&.join("\n")
+        )
+        run.add_log("Execution failed: #{e.message}", level: :error)
+        raise
+      ensure
+        run.broadcast_update
+      end
+    end
+
+    private
+
+    def execute_agent(agent_record, run)
+      AgentExecutionService.call(agent_record, run)
+    end
+  end
+end

data/app/jobs/action_agent/application_job.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module ActionAgent
+  # Base class for all Dashboard engine jobs.
+  class ApplicationJob < ActiveJob::Base
+    # Retry failed jobs
+    retry_on StandardError, wait: :polynomially_longer, attempts: 3
+
+    # Discard jobs for records that no longer exist
+    discard_on ActiveRecord::RecordNotFound
+  end
+end

data/app/jobs/action_agent/process_telemetry_traces_job.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module ActionAgent
+  # Processes telemetry traces received from ActiveAgent clients.
+  #
+  # This job handles the asynchronous processing of trace data to avoid
+  # blocking the ingestion endpoint. It:
+  # - Creates TelemetryTrace records for each trace
+  # - Updates aggregate statistics
+  # - Handles any errors gracefully
+  #
+  # @example Local mode
+  #   ActionAgent::ProcessTelemetryTracesJob.perform_later(
+  #     traces: [...],
+  #     sdk_info: { name: "activeagent", version: "0.5.0" },
+  #     received_at: "2024-01-15T10:30:00Z"
+  #   )
+  #
+  # @example Multi-tenant mode
+  #   ActionAgent::ProcessTelemetryTracesJob.perform_later(
+  #     account_id: 1,
+  #     traces: [...],
+  #     sdk_info: { name: "activeagent", version: "0.5.0" },
+  #     received_at: "2024-01-15T10:30:00Z"
+  #   )
+  #
+  class ProcessTelemetryTracesJob < ::ActiveJob::Base
+    queue_as :default
+
+    # Maximum traces to process in a single job to avoid memory issues
+    MAX_TRACES_PER_JOB = 100
+
+    def perform(account_id: nil, traces:, sdk_info:, received_at:)
+      account = resolve_account(account_id)
+
+      # In multi-tenant mode, require an account
+      if ActionAgent.multi_tenant? && account.nil?
+        Rails.logger.warn("[ProcessTelemetryTracesJob] Skipping traces - no valid account")
+        return
+      end
+
+      # Process in bounded slices; anything beyond the cap is re-enqueued
+      # rather than silently dropped (the client already received 202).
+      remainder = traces.drop(MAX_TRACES_PER_JOB)
+      traces = traces.take(MAX_TRACES_PER_JOB)
+      if remainder.any?
+        self.class.perform_later(
+          account_id: account_id, traces: remainder,
+          sdk_info: sdk_info, received_at: received_at
+        )
+      end
+
+      traces.each do |trace|
+        process_trace(trace, sdk_info, account)
+      rescue StandardError => e
+        Rails.logger.error(
+          "[ProcessTelemetryTracesJob] Failed to process trace #{trace['trace_id']}: " \
+          "#{e.class} - #{e.message}"
+        )
+      end
+    end
+
+    private
+
+    def resolve_account(account_id)
+      return nil unless ActionAgent.multi_tenant?
+      return nil unless account_id
+
+      account_class = ActionAgent.account_class.constantize
+      account_class.find_by(id: account_id)
+    end
+
+    def process_trace(trace, sdk_info, account)
+      model = ActionAgent.trace_model
+
+      # Build uniqueness scope
+      scope = model.where(trace_id: trace["trace_id"])
+      scope = scope.where(account: account) if ActionAgent.multi_tenant? && account
+
+      # Skip if trace already exists (idempotency)
+      return if scope.exists?
+
+      model.create_from_payload(trace, sdk_info, account: account)
+    end
+  end
+end

data/app/jobs/action_agent/sandbox_cleanup_job.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module ActionAgent
+  class SandboxCleanupJob < ApplicationJob
+    queue_as :sandboxes
+
+    # Clean up Cloud Run resources for an expired sandbox
+    def perform(sandbox_session_id)
+      sandbox = SandboxSession.find_by(id: sandbox_session_id)
+      return unless sandbox
+
+      Rails.logger.info("Cleaning up sandbox: #{sandbox.session_id}")
+
+      # Delete Cloud Run Job if exists
+      if sandbox.cloud_run_job_id.present? && !Rails.env.development?
+        delete_cloud_run_job(sandbox.cloud_run_job_id)
+      end
+
+      # Optionally delete old sandbox records
+      # For now, keep for analytics
+      sandbox.update!(cloud_run_url: nil, cloud_run_job_id: nil)
+    end
+
+    # Periodic cleanup of all expired sandboxes
+    def self.cleanup_expired!
+      SandboxSession.expired_sessions.active.find_each do |sandbox|
+        sandbox.expire!
+      end
+    end
+
+    private
+
+    def delete_cloud_run_job(job_id)
+      require "google/cloud/run/v2"
+
+      client = Google::Cloud::Run::V2::Jobs::Client.new
+      client.delete_job(name: job_id)
+    rescue => e
+      Rails.logger.warn("Failed to delete Cloud Run job #{job_id}: #{e.message}")
+    end
+  end
+end