actionagent 0.0.0 → 1.2.0

data/app/models/concerns/action_agent/adapter_aware.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module ActionAgent
+  # The dashboard's aggregate queries are written portably, but a few of
+  # them have a much faster PostgreSQL form (jsonb traversal, containment).
+  # This is how those queries choose which one to run.
+  module AdapterAware
+    extend ActiveSupport::Concern
+
+    class_methods do
+      # True when the backing store is PostgreSQL.
+      def postgres?
+        connection.adapter_name.to_s.downcase.include?("postgres")
+      end
+
+      # SQL grouping +column+ into hourly buckets. PostgreSQL has
+      # date_trunc; SQLite and MySQL get the equivalent format string.
+      # Pair with hour_bucket_epoch, which normalises what each adapter
+      # returns into epoch seconds so callers compare buckets the same way.
+      def hour_bucket_sql(column = :timestamp)
+        case connection.adapter_name.to_s.downcase
+        when /postgres/ then "date_trunc('hour', #{column})"
+        when /mysql/ then "DATE_FORMAT(#{column}, '%Y-%m-%d %H:00:00')"
+        else "strftime('%Y-%m-%d %H:00:00', #{column})"
+        end
+      end
+
+      # SQL matching rows whose JSON array +column+ actually has entries.
+      #
+      # `where.not(column: [])` cannot express this and is not a slower way
+      # of doing it — Active Record reads the empty array as an empty IN
+      # list, so the condition compiles to `1=1` and matches every row.
+      # +column+ is always a literal from this codebase, never user input.
+      def json_array_not_empty_sql(column)
+        case connection.adapter_name.to_s.downcase
+        when /postgres/ then "COALESCE(jsonb_array_length(#{column}::jsonb), 0) > 0"
+        when /mysql/ then "COALESCE(JSON_LENGTH(#{column}), 0) > 0"
+        else "COALESCE(json_array_length(#{column}), 0) > 0"
+        end
+      end
+
+      # PostgreSQL hands back a Time; the others a UTC string.
+      def hour_bucket_epoch(value)
+        return value.to_i if value.is_a?(Time) || value.is_a?(DateTime)
+
+        Time.find_zone("UTC").parse(value.to_s).to_i
+      end
+    end
+  end
+end

data/app/models/concerns/action_agent/ownable.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module ActionAgent
+  # Attaches a dashboard record to whatever the host app calls an owner.
+  #
+  # Each model names the associations that could own it, most preferred
+  # first, and the first one the host app has actually configured wins:
+  #
+  #   class Agent < ApplicationRecord
+  #     include Ownable
+  #     owned_by :user, :account
+  #   end
+  #
+  # So an app with users scopes agents per user, an app with only accounts
+  # scopes them per account, and a single-user self-hosted install declares
+  # neither association and owns everything implicitly. That ordering is
+  # per-model on purpose: an app can reasonably keep agents per user while
+  # keeping API keys per account, and the platform does exactly that.
+  #
+  # Both foreign keys exist in the engine's schema either way, so moving a
+  # deployment between shapes is a configuration change, not a migration.
+  module Ownable
+    extend ActiveSupport::Concern
+
+    CLASS_FOR = { account: :account_class, user: :user_class }.freeze
+
+    class_methods do
+      # Declares the candidate owners for this model, most preferred first.
+      def owned_by(*candidates)
+        @owner_candidates = candidates.map(&:to_sym)
+
+        @owner_candidates.each do |candidate|
+          class_name = ActionAgent.public_send(CLASS_FOR.fetch(candidate))
+          next if class_name.blank?
+
+          belongs_to candidate, class_name: class_name, optional: true
+        end
+      end
+
+      def owner_candidates
+        @owner_candidates || []
+      end
+
+      # The association this install owns the model through, or nil when the
+      # host app configured no owner model at all.
+      def owner_association
+        owner_candidates.find { |c| ActionAgent.public_send(CLASS_FOR.fetch(c)).present? }
+      end
+
+      # Scopes to records owned by +owner+.
+      #
+      # A nil owner is read two different ways, and the difference is the
+      # whole point:
+      #
+      #   * No owner model configured at all — the single-user self-hosted
+      #     install. Nothing is owned, so everything is visible.
+      #   * An owner model IS configured but did not resolve — a signed-out
+      #     request, or a resolver that returned nil. Returning `all` here
+      #     would hand one tenant every other tenant's records, so it
+      #     returns nothing instead.
+      def for_owner(owner)
+        return all if owner_association.nil?
+        return none if owner.nil?
+
+        case owner_association
+        when :account then where(account_id: owner.id)
+        when :user then where(user_id: owner.id)
+        else all
+        end
+      end
+    end
+
+    # The record's owner under the current configuration, or nil.
+    def owner
+      association = self.class.owner_association
+      association && public_send(association)
+    end
+
+    # Assigns +owner+ to whichever association this install uses. A no-op
+    # when the host app configured no owner model.
+    def owner=(record)
+      association = self.class.owner_association
+      public_send(:"#{association}=", record) if association
+    end
+  end
+end

data/app/models/concerns/action_agent/session_recordable.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module ActionAgent
+  # Concern for adding session recording to models that track browser interactions
+  #
+  # Include this in models like AgentRun or SandboxSession to enable
+  # automatic session recording for playback and handoff.
+  #
+  # Usage:
+  #   class AgentRun < ApplicationRecord
+  #     include SessionRecordable
+  #   end
+  #
+  #   # Start recording
+  #   run.start_session_recording!
+  #
+  #   # Record an action
+  #   run.record_browser_action!(type: :click, selector: "#submit", screenshot: png_data)
+  #
+  #   # Complete recording
+  #   run.complete_session_recording!
+  #
+  module SessionRecordable
+    extend ActiveSupport::Concern
+
+    included do
+      has_one :session_recording, dependent: :destroy
+    end
+
+    # Start a new session recording
+    def start_session_recording!(name: nil)
+      return session_recording if session_recording&.recording?
+
+      create_session_recording!(
+        name: name || default_recording_name,
+        status: :recording,
+        metadata: { started_at: Time.current.iso8601 }
+      )
+    end
+
+    # Record a browser action
+    def record_browser_action!(type:, selector: nil, value: nil, screenshot: nil, dom_snapshot: nil, metadata: {})
+      return unless session_recording&.recording?
+
+      session_recording.record_action!(
+        action_type: type.to_s,
+        selector: selector,
+        value: value,
+        screenshot: screenshot,
+        dom_snapshot: dom_snapshot,
+        metadata: metadata
+      )
+    end
+
+    # Complete the recording
+    def complete_session_recording!
+      session_recording&.complete!
+    end
+
+    # Fail the recording
+    def fail_session_recording!(error_message = nil)
+      session_recording&.fail!(error_message)
+    end
+
+    # Check if recording is active
+    def recording_active?
+      session_recording&.recording?
+    end
+
+    # Get the session recording service
+    def recording_service
+      return nil unless session_recording
+
+      SessionRecordingService.new(session_recording)
+    end
+
+    private
+
+    def default_recording_name
+      prefix = if respond_to?(:name) && name.present?
+        name.parameterize
+      elsif respond_to?(:agent) && agent&.name
+        agent.name.parameterize
+      else
+        "session"
+      end
+
+      "#{prefix}_#{Time.current.strftime('%Y%m%d_%H%M%S')}"
+    end
+  end
+end

data/app/queries/action_agent/agent_executions.rb

@@ -0,0 +1,201 @@
+# frozen_string_literal: true
+
+module ActionAgent
+  # One agent execution, whoever ran it.
+  #
+  # The platform records executions it initiates as AgentRun rows; agents
+  # running inside a customer's own app only ever produce a TelemetryTrace.
+  # They are the same grain — one attempt at one agent action — so the
+  # dashboard treats them as one list with a `source` discriminator rather
+  # than as two competing tabs:
+  #
+  #   dashboard — an AgentRun (we executed it; has lifecycle, logs, cancel)
+  #   reported  — a trace no AgentRun claims (their app executed it)
+  #
+  # A platform execution usually writes BOTH an AgentRun and a trace sharing a
+  # trace_id, so traces are counted only when unclaimed. The reverse is not
+  # symmetric: a run that fails before its root span exists has no trace at
+  # all, which is why runs — not traces — are the authoritative source when
+  # both exist.
+  #
+  # Distinct from AgentContext, which is a *stream*: one durable conversation
+  # per agent action that many executions append to. A stream is a parent of
+  # executions, not an alternative to them.
+  class AgentExecutions
+    SOURCES = %w[dashboard reported].freeze
+
+    # What to rank a list of executions by. "Popular" is deliberately absent:
+    # it's an aggregate property of an agent or a model, not of one attempt —
+    # the agent list and the metrics table sort by it, this list can't.
+    SORTS = {
+      "recent" => "Most recent",
+      "longest" => "Longest running",
+      "cost" => "Highest cost",
+      "tokens" => "Most tokens"
+    }.freeze
+    DEFAULT_SORT = "recent"
+
+    Row = Struct.new(
+      :id, :source, :status, :occurred_at, :duration_ms, :tokens,
+      :input_tokens, :output_tokens, :cost,
+      :trace_id, :agent_id, :action_name, :provider, :model,
+      :input_preview, :output_preview, :error_message,
+      keyword_init: true
+    ) do
+      def as_json(*)
+        to_h.transform_values { |value| value.is_a?(Time) ? value.iso8601(3) : value }
+      end
+
+      # Runs are addressable by record id; reported executions only by trace.
+      def to_param
+        source == "dashboard" ? id.to_s : "trace-#{id}"
+      end
+    end
+
+    # @param agents [ActiveRecord::Relation, Array<Agent>] scope to these agents
+    # @param owner [Object, nil] tenant whose reported traces are in scope;
+    #   nil in a single-tenant install, where every trace is in scope
+    # @param window_minutes [Integer, nil] nil means all time
+    # @param source [String, nil] "dashboard" | "reported" | nil for both
+    # @param status [String, nil] AgentRun status; also filters reported by OK/ERROR
+    # @param sort [String, nil] one of SORTS; unknown values fall back to recent
+    def initialize(agents:, owner: nil, window_minutes: nil, source: nil, status: nil, sort: nil)
+      @agent_ids = Array(agents.respond_to?(:pluck) ? agents.pluck(:id) : agents.map(&:id))
+      @owner = owner
+      @window_minutes = window_minutes
+      @source = source.presence
+      @status = status.presence
+      @sort = SORTS.key?(sort.to_s) ? sort.to_s : DEFAULT_SORT
+    end
+
+    # Ranked by the chosen dimension, descending. The two sources can only be
+    # ordered together in Ruby (no SQL union), which is also why this always
+    # ranks the whole window rather than the page.
+    def page(page: 1, per_page: 20)
+      all = sorted_rows
+      offset = (page.to_i - 1) * per_page.to_i
+      { rows: all[offset, per_page.to_i] || [], total: all.size }
+    end
+
+    def sorted_rows
+      # Ties (and rows missing the sorted value entirely — an execution still
+      # running has no duration) fall back to newest first, so the list never
+      # reorders arbitrarily between requests.
+      rows.sort_by { |row| [ -sort_value(row), -(row.occurred_at || Time.at(0)).to_f ] }
+    end
+
+    def rows
+      @rows ||= (include_dashboard? ? run_rows : []) + (include_reported? ? trace_rows : [])
+    end
+
+    # Traces attributed to these agents that no AgentRun already accounts for.
+    # Shared with AgentScorecard so every surface counts the same executions.
+    def self.unclaimed_traces(agent_ids, since: nil, owner: nil)
+      traces = ActionAgent.trace_model
+      runs_table = AgentRun.table_name
+      traces_table = traces.table_name
+
+      scope = traces.where(agent_id: agent_ids)
+      scope = scope.for_account(owner) if owner
+      scope = scope.where(timestamp: since..) if since
+      scope
+        .joins(<<~SQL.squish)
+          LEFT JOIN #{runs_table}
+            ON #{runs_table}.trace_id = #{traces_table}.trace_id
+           AND #{runs_table}.agent_id = #{traces_table}.agent_id
+        SQL
+        .where(runs_table => { id: nil })
+    end
+
+    private
+
+    def sort_value(row)
+      case @sort
+      when "longest" then row.duration_ms.to_f
+      when "cost" then row.cost.to_f
+      when "tokens" then row.tokens.to_i
+      else (row.occurred_at || Time.at(0)).to_f
+      end
+    end
+
+    def include_dashboard? = @source.nil? || @source == "dashboard"
+    # A single-tenant dashboard reads every trace it holds. A multi-tenant
+    # one has no business reading any without a tenant to scope them to.
+    def include_reported?
+      return false if ActionAgent.multi_tenant? && @owner.nil?
+
+      @source.nil? || @source == "reported"
+    end
+
+    def since = @window_minutes ? @window_minutes.to_i.minutes.ago : nil
+
+    def run_rows
+      scope = AgentRun.where(agent_id: @agent_ids)
+      scope = scope.where(created_at: since..) if since
+      scope = scope.where(status: @status) if @status
+
+      scope.map do |run|
+        model = run.output_metadata&.dig("model")
+        Row.new(
+          id: run.id,
+          source: "dashboard",
+          status: run.status,
+          occurred_at: run.created_at,
+          duration_ms: run.calculated_duration_ms,
+          tokens: run.total_tokens.to_i,
+          input_tokens: run.input_tokens.to_i,
+          output_tokens: run.output_tokens.to_i,
+          cost: ModelPricing.estimate(
+            model: model,
+            input_tokens: run.input_tokens,
+            output_tokens: run.output_tokens
+          ),
+          trace_id: run.trace_id,
+          agent_id: run.agent_id,
+          action_name: run.action_name,
+          provider: run.output_metadata&.dig("provider"),
+          model: model,
+          input_preview: run.input_prompt.to_s.truncate(160),
+          output_preview: run.output.to_s.truncate(160).presence,
+          error_message: run.error_message
+        )
+      end
+    end
+
+    def trace_rows
+      scope = self.class.unclaimed_traces(@agent_ids, since: since, owner: @owner)
+      # A run status filter has no exact analogue on a trace; map the two that
+      # do rather than silently ignoring the filter.
+      scope = scope.where(status: "ERROR") if @status == "failed"
+      scope = scope.where.not(status: "ERROR") if @status == "complete"
+      return [] if @status.present? && !%w[failed complete].include?(@status)
+
+      scope.map do |trace|
+        model = trace.model
+        Row.new(
+          id: trace.id,
+          source: "reported",
+          status: trace.status == "ERROR" ? "failed" : "complete",
+          occurred_at: trace.timestamp,
+          duration_ms: trace.total_duration_ms&.round,
+          tokens: trace.total_tokens.to_i,
+          input_tokens: trace.total_input_tokens.to_i,
+          output_tokens: trace.total_output_tokens.to_i,
+          cost: ModelPricing.estimate(
+            model: model,
+            input_tokens: trace.total_input_tokens,
+            output_tokens: trace.total_output_tokens
+          ),
+          trace_id: trace.trace_id,
+          agent_id: trace.agent_id,
+          action_name: trace.agent_action,
+          provider: trace.provider,
+          model: model,
+          input_preview: nil,
+          output_preview: nil,
+          error_message: trace.error_message
+        )
+      end
+    end
+  end
+end

data/app/serializers/action_agent/agent_message_serializer.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module ActionAgent
+  # Serializes AgentMessage records for the shared InteractionStream UI
+  # (Interactions view and the agent Conversation History run detail).
+  class AgentMessageSerializer
+    def self.call(message)
+      {
+        id: message.id,
+        role: message.role,
+        content: message.content,
+        tool_name: message.tool_name,
+        tool_call_id: message.tool_call_id,
+        tool_calls: message.tool_calls_data,
+        tool_arguments: message.tool_arguments.presence,
+        tool_result: message.tool_result,
+        duration_ms: message.metadata&.dig("duration_ms"),
+        content_checksum: message.content_checksum,
+        created_at: message.created_at.iso8601(3)
+      }
+    end
+  end
+end

data/app/serializers/action_agent/interaction_preview.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module ActionAgent
+  # The two lines a collapsed interaction row shows — what the stream was
+  # asked, and what it finally answered. Both sources of an interaction produce
+  # them: solid_agent contexts (Api::InteractionsController) and reported
+  # traces (TraceInteractionSerializer), so a list mixing the two reads the
+  # same way either side of the row came from.
+  module InteractionPreview
+    # One line each. The list is fifty streams deep, and the row clips to a
+    # single line anyway — sending the whole conversation to be truncated in
+    # the browser would pay for text nobody reads.
+    LIMIT = 300
+
+    def self.line(value)
+      text = value.to_s.squish
+      return nil if text.blank?
+
+      text.truncate(LIMIT)
+    end
+  end
+end

data/app/serializers/action_agent/telemetry_trace_serializer.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module ActionAgent
+  # Serializes TelemetryTrace records (gem span payloads) into the view-model
+  # consumed by the dashboard's TracesView: relative span offsets for the
+  # waterfall timeline, nesting depth, and token totals.
+  class TelemetryTraceSerializer
+    # Span types understood by the dashboard timeline (superset of the gem's
+    # ActiveAgent::Telemetry::Span::TYPES).
+    KNOWN_SPAN_TYPES = %w[root prompt generate llm tool thinking embedding response error].freeze
+
+    def self.summary(trace)
+      new(trace).summary
+    end
+
+    def self.detail(trace)
+      new(trace).detail
+    end
+
+    def initialize(trace)
+      @trace = trace
+    end
+
+    def summary
+      {
+        id: @trace.id,
+        trace_id: @trace.trace_id,
+        short_id: @trace.trace_id&.first(8),
+        agent: @trace.agent_class,
+        action: @trace.agent_action,
+        display_name: @trace.display_name,
+        service_name: @trace.service_name,
+        environment: @trace.environment,
+        provider: @trace.provider,
+        model: @trace.model,
+        status: @trace.status,
+        error: @trace.error_message,
+        duration_ms: @trace.total_duration_ms&.to_f&.round(2),
+        timestamp: @trace.timestamp&.iso8601(3),
+        timestamp_ms: @trace.timestamp&.to_f&.*(1000)&.round,
+        tokens: {
+          input: @trace.total_input_tokens || 0,
+          output: @trace.total_output_tokens || 0,
+          thinking: @trace.total_thinking_tokens || 0,
+          total: @trace.total_tokens
+        },
+        estimated_cost: ModelPricing.estimate(
+          model: @trace.model,
+          input_tokens: @trace.total_input_tokens,
+          output_tokens: @trace.total_output_tokens
+        ),
+        spans: serialized_spans
+      }
+    end
+
+    def detail
+      summary.merge(
+        resource_attributes: @trace.resource_attributes,
+        sdk_info: @trace.sdk_info
+      )
+    end
+
+    private
+
+    # Maps raw gem spans (start_time/end_time ISO strings, parent_span_id
+    # links) to waterfall rows with millisecond offsets relative to the root
+    # span and a nesting depth.
+    def serialized_spans
+      spans = Array(@trace.spans)
+      return [] if spans.empty?
+
+      by_id = spans.index_by { |s| s["span_id"] }
+      root = spans.find { |s| s["parent_span_id"].nil? } || spans.first
+      root_start = parse_time(root["start_time"])
+
+      spans.map do |span|
+        start = parse_time(span["start_time"])
+        offset = (root_start && start) ? ((start - root_start) * 1000).round(2) : 0
+
+        {
+          span_id: span["span_id"],
+          name: span["name"],
+          type: normalized_type(span),
+          start: [ offset, 0 ].max,
+          duration: span["duration_ms"]&.to_f&.round(2) || 0,
+          nested: depth_of(span, by_id),
+          status: span["status"],
+          error: span["status"] == "ERROR",
+          tokens: span["tokens"],
+          attributes: span["attributes"]
+        }
+      end
+    end
+
+    def normalized_type(span)
+      type = span["type"].to_s
+      KNOWN_SPAN_TYPES.include?(type) ? type : "root"
+    end
+
+    def depth_of(span, by_id)
+      depth = 0
+      current = span
+      while (parent_id = current["parent_span_id"])
+        parent = by_id[parent_id]
+        break unless parent
+
+        depth += 1
+        current = parent
+        break if depth > 10
+      end
+      depth
+    end
+
+    def parse_time(value)
+      return nil if value.blank?
+
+      Time.zone.parse(value.to_s)
+    rescue ArgumentError
+      nil
+    end
+  end
+end