actionagent 0.0.0 → 1.2.0

data/app/models/action_agent/sandbox_session.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+module ActionAgent
+  class SandboxSession < ApplicationRecord
+    include Ownable
+    owned_by :user, :account
+
+    belongs_to :agent_template, optional: true
+
+    # Session statuses
+    enum :status, {
+      pending: 0,
+      provisioning: 1,
+      ready: 2,
+      running: 3,
+      completed: 4,
+      expired: 5,
+      failed: 6
+    }
+
+    # Sandbox types
+    SANDBOX_TYPES = %w[playwright_mcp terminal research].freeze
+
+    # Free tier limits
+    FREE_TIER_LIMITS = {
+      max_runs: 10,
+      timeout_seconds: 300,
+      max_tokens: 50_000,
+      session_duration_minutes: 15
+    }.freeze
+
+    # Validations
+    validates :session_id, presence: true, uniqueness: true
+    validates :sandbox_type, inclusion: { in: SANDBOX_TYPES }
+
+    # Callbacks
+    before_validation :generate_session_id, on: :create
+    before_create :set_expiration
+
+    # Scopes
+    scope :active, -> { where(status: [ :pending, :provisioning, :ready, :running ]) }
+    scope :expired_sessions, -> { where("expires_at < ?", Time.current) }
+    scope :by_type, ->(type) { where(sandbox_type: type) }
+    scope :anonymous, -> { where(user_id: nil) }
+    scope :recent, -> { order(created_at: :desc) }
+
+    # Catalog entries for the MCP servers this session was started with.
+    # Unknown keys are dropped rather than raising — a session outlives a
+    # catalog edit.
+    def mcp_catalog_entries
+      Array(mcp_servers).filter_map { |key| McpCatalog.find(key) }
+    end
+
+    # Check if session is still valid
+    def active?
+      !expired? && !failed? && !completed? && expires_at > Time.current
+    end
+
+    # Check if can run more tasks
+    def can_run?
+      active? && runs_count < max_runs
+    end
+
+    # Record a new run (thread-safe for parallel execution)
+    def record_run!(task:, result:, duration_ms:, tokens:, screenshots: [], provider: nil)
+      run = {
+        id: SecureRandom.uuid,
+        task: task,
+        result: result,
+        duration_ms: duration_ms,
+        tokens: tokens,
+        screenshots: screenshots,
+        provider: provider,
+        status: "completed",
+        created_at: Time.current.iso8601
+      }
+
+      # Use pessimistic locking to prevent race conditions when multiple providers run in parallel
+      with_lock do
+        reload # Reload to get the latest state
+        self.runs = runs + [ run ]
+        self.runs_count = runs.size
+        self.total_tokens += tokens
+        self.total_duration_ms += duration_ms
+        self.last_activity_at = Time.current
+        save!
+      end
+
+      run
+    end
+
+    # Provision the Cloud Run sandbox
+    def provision!
+      return if provisioning? || ready?
+
+      update!(status: :provisioning)
+
+      # In development, run synchronously for immediate feedback
+      if Rails.env.development? || Rails.env.test?
+        SandboxProvisionJob.perform_now(id)
+      else
+        SandboxProvisionJob.perform_later(id)
+      end
+    end
+
+    # Mark as ready with Cloud Run URL
+    def mark_ready!(cloud_run_url:, cloud_run_job_id: nil)
+      update!(
+        status: :ready,
+        cloud_run_url: cloud_run_url,
+        cloud_run_job_id: cloud_run_job_id
+      )
+    end
+
+    # Expire the session
+    def expire!
+      update!(status: :expired)
+      # Cleanup Cloud Run resources
+      SandboxCleanupJob.perform_later(id) if cloud_run_job_id.present?
+    end
+
+    # Summary for API responses
+    def summary
+      {
+        id: id,
+        session_id: session_id,
+        sandbox_type: sandbox_type,
+        status: status,
+        runs_count: runs_count,
+        max_runs: max_runs,
+        total_tokens: total_tokens,
+        expires_at: expires_at&.iso8601,
+        created_at: created_at.iso8601,
+        cloud_run_url: cloud_run_url,
+        mcp_servers: Array(mcp_servers)
+      }
+    end
+
+    # Detailed info including runs
+    def details
+      summary.merge(
+        runs: runs,
+        total_duration_ms: total_duration_ms,
+        last_activity_at: last_activity_at&.iso8601
+      )
+    end
+
+    private
+
+    def generate_session_id
+      self.session_id ||= SecureRandom.uuid
+    end
+
+    def set_expiration
+      self.expires_at ||= FREE_TIER_LIMITS[:session_duration_minutes].minutes.from_now
+      self.max_runs ||= FREE_TIER_LIMITS[:max_runs]
+      self.timeout_seconds ||= FREE_TIER_LIMITS[:timeout_seconds]
+    end
+  end
+end

data/app/models/action_agent/session_recording.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+module ActionAgent
+  class SessionRecording < ApplicationRecord
+    include Ownable
+    owned_by :user, :account
+
+    belongs_to :agent_run, optional: true
+    belongs_to :sandbox_session, optional: true
+
+    has_many :recording_actions, dependent: :destroy
+    has_many :recording_snapshots, dependent: :destroy
+
+    enum :status, { recording: 0, completed: 1, failed: 2 }
+
+    validates :status, presence: true
+    validate :must_have_parent, unless: -> { demo_recording? || user_session? }
+
+    scope :recent, -> { order(created_at: :desc) }
+    scope :for_agent, ->(agent_id) { joins(:agent_run).where(agent_runs: { agent_id: agent_id }) }
+    scope :demo, -> { where(name: "lander_demo") }
+    scope :user_sessions, -> { where("name LIKE ?", "user_takeover_%") }
+
+    # Check if this is a demo recording (doesn't require parent)
+    def demo_recording?
+      name&.start_with?("lander_") || name == "demo"
+    end
+
+    # Check if this is a user takeover session (doesn't require parent)
+    def user_session?
+      name&.start_with?("user_takeover_")
+    end
+
+    # Start a new recording session
+    def self.start!(agent_run: nil, sandbox_session: nil, name: nil)
+      create!(
+        agent_run: agent_run,
+        sandbox_session: sandbox_session,
+        name: name || generate_name(agent_run, sandbox_session),
+        status: :recording,
+        metadata: { started_at: Time.current.iso8601 }
+      )
+    end
+
+    # Start a user takeover session (for lander demo analytics)
+    def self.start_user_session!(visitor_id: nil, parent_demo_id: nil, page_url: nil)
+      create!(
+        name: "user_takeover_#{Time.current.strftime('%Y%m%d_%H%M%S')}_#{SecureRandom.hex(4)}",
+        status: :recording,
+        metadata: {
+          started_at: Time.current.iso8601,
+          session_type: "user_takeover",
+          visitor_id: visitor_id,
+          parent_demo_id: parent_demo_id,
+          page_url: page_url,
+          user_agent: nil # Will be set from request
+        }
+      )
+    end
+
+    # Record a browser action
+    def record_action!(action_type:, selector: nil, value: nil, screenshot: nil, dom_snapshot: nil, metadata: {})
+      raise "Recording already completed" unless recording?
+
+      action = recording_actions.create!(
+        action_type: action_type,
+        sequence: next_sequence,
+        timestamp_ms: elapsed_ms,
+        selector: selector,
+        value: value,
+        metadata: metadata
+      )
+
+      # Handle screenshot attachment if provided
+      if screenshot.present?
+        snapshot = store_snapshot(screenshot, :screenshot, action)
+        action.update!(screenshot_key: snapshot.storage_key)
+      end
+
+      # Handle DOM snapshot if provided
+      if dom_snapshot.present?
+        snapshot = store_snapshot(dom_snapshot, :dom, action)
+        action.update!(dom_snapshot_key: snapshot.storage_key)
+      end
+
+      increment!(:action_count)
+      action
+    end
+
+    # Complete the recording
+    def complete!
+      return unless recording?
+
+      update!(
+        status: :completed,
+        duration_ms: elapsed_ms,
+        metadata: metadata.merge(completed_at: Time.current.iso8601)
+      )
+    end
+
+    # Mark recording as failed
+    def fail!(error_message = nil)
+      return unless recording?
+
+      update!(
+        status: :failed,
+        duration_ms: elapsed_ms,
+        metadata: metadata.merge(
+          failed_at: Time.current.iso8601,
+          error: error_message
+        )
+      )
+    end
+
+    # Get timeline data for playback
+    def timeline
+      recording_actions.order(:sequence).map do |action|
+        {
+          id: action.id,
+          type: action.action_type,
+          sequence: action.sequence,
+          timestamp_ms: action.timestamp_ms,
+          selector: action.selector,
+          value: action.value,
+          screenshot_key: action.screenshot_key,
+          metadata: action.metadata
+        }
+      end
+    end
+
+    private
+
+    def must_have_parent
+      return if agent_run.present? || sandbox_session.present?
+
+      errors.add(:base, "must belong to an agent_run or sandbox_session")
+    end
+
+    def self.generate_name(agent_run, sandbox_session)
+      prefix = if agent_run&.agent
+        agent_run.agent.name.parameterize
+      elsif sandbox_session&.agent_template
+        sandbox_session.agent_template.name.parameterize
+      else
+        "session"
+      end
+
+      "#{prefix}_#{Time.current.strftime('%Y%m%d_%H%M%S')}"
+    end
+
+    def next_sequence
+      (recording_actions.maximum(:sequence) || 0) + 1
+    end
+
+    def elapsed_ms
+      ((Time.current - created_at) * 1000).to_i
+    end
+
+    def store_snapshot(data, snapshot_type, action = nil)
+      storage_key = generate_storage_key(snapshot_type, action&.sequence)
+
+      # For now, store metadata - actual file upload handled by service
+      recording_snapshots.create!(
+        recording_action: action,
+        storage_key: storage_key,
+        snapshot_type: snapshot_type,
+        file_size_bytes: data.bytesize
+      )
+    end
+
+    def generate_storage_key(snapshot_type, sequence = nil)
+      parts = [ "recordings", id, snapshot_type.to_s ]
+      parts << sequence.to_s if sequence
+      parts << SecureRandom.hex(8)
+      parts.join("/")
+    end
+  end
+end

data/app/models/action_agent/telemetry_trace.rb

@@ -0,0 +1,357 @@
+# frozen_string_literal: true
+
+module ActionAgent
+  # Stores telemetry traces from ActiveAgent clients.
+  #
+  # Each trace represents a complete generation lifecycle, including prompt
+  # preparation, LLM calls, tool invocations, and error handling.
+  #
+  # This model supports two modes:
+  # - Local mode: No account association (single-tenant, self-hosted)
+  # - Multi-tenant mode: With account association (for activeagents.ai platform)
+  #
+  # @example Creating a trace from ingested data (local mode)
+  #   ActionAgent::TelemetryTrace.create_from_payload(trace_payload, sdk_info)
+  #
+  # @example Creating a trace with account (multi-tenant mode)
+  #   ActionAgent::TelemetryTrace.create_from_payload(trace_payload, sdk_info, account: account)
+  #
+  class TelemetryTrace < ::ActiveRecord::Base
+    include ActionAgent::AdapterAware
+
+    self.table_name = "active_agent_telemetry_traces"
+
+    # Optional account association for multi-tenant mode
+    # The host app can add: belongs_to :account if needed
+    if ActionAgent.multi_tenant?
+      belongs_to :account, class_name: ActionAgent.account_class
+    end
+
+    # Status values for traces
+    STATUS_OK = "OK"
+    STATUS_ERROR = "ERROR"
+    STATUS_UNSET = "UNSET"
+
+    validates :trace_id, presence: true
+
+    # Scopes
+    scope :recent, -> { order(timestamp: :desc) }
+    scope :with_errors, -> { where(status: STATUS_ERROR) }
+    scope :for_service, ->(name) { where(service_name: name) }
+    scope :for_environment, ->(env) { where(environment: env) }
+    scope :for_agent, ->(agent_class) { where(agent_class: agent_class) }
+    scope :for_date_range, ->(start_date, end_date) { where(timestamp: start_date..end_date) }
+    # The dashboard agent this trace was attributed to on ingest, if any.
+    belongs_to :agent, class_name: "ActionAgent::Agent", optional: true
+
+    scope :for_account, ->(account) { where(account: account) if ActionAgent.multi_tenant? }
+
+    # Creates a TelemetryTrace from an ingested trace payload.
+    #
+    # Extracts relevant data from the trace payload and stores it in a
+    # normalized format for querying and analysis.
+    #
+    # @param trace [Hash] The trace payload from ActiveAgent::Telemetry
+    # @param sdk_info [Hash] SDK metadata
+    # @param account [Object, nil] Optional account for multi-tenant mode
+    # @return [TelemetryTrace] The created trace
+    # Plucks [llm_model, *columns] per trace, where llm_model comes from the
+    # first llm span. PostgreSQL digs into the spans jsonb in SQL so span
+    # payloads never reach Ruby; other adapters read the column back and dig
+    # in Ruby, which costs more but keeps the dashboard adapter-agnostic.
+    def self.pluck_with_llm_model(scope, *columns)
+      if postgres?
+        scope.pluck(
+          Arel.sql(
+            # spans is cast rather than assumed to be jsonb: the column is
+            # json on every install created before the migration template
+            # started picking jsonb per adapter, and jsonb_array_elements
+            # rejects a json argument outright.
+            "(SELECT s.value -> 'attributes' ->> 'llm.model' " \
+            "FROM jsonb_array_elements(spans::jsonb) AS s " \
+            "WHERE s.value ->> 'type' = 'llm' LIMIT 1)"
+          ),
+          *columns
+        )
+      else
+        scope.pluck(:spans, *columns).map do |spans, *rest|
+          llm = Array(spans).find { |span| span.is_a?(Hash) && span["type"].to_s == "llm" }
+          [ llm&.dig("attributes", "llm.model"), *rest ]
+        end
+      end
+    end
+
+    def self.create_from_payload(trace, sdk_info = {}, account: nil)
+      spans = trace["spans"] || []
+      root_span = spans.find { |s| s["parent_span_id"].nil? } || spans.first || {}
+
+      total_duration = root_span["duration_ms"]
+
+      # Instrumentation mirrors LLM token usage onto the root span for
+      # display, so summing every span double-counts. When child spans
+      # carry token data, they are the source of truth; the root span only
+      # counts for single-span traces.
+      counted_spans = spans.reject { |s| s["parent_span_id"].nil? }
+      counted_spans = spans if counted_spans.none? { |s| span_token_sum(s).positive? }
+
+      total_input = 0
+      total_output = 0
+      total_thinking = 0
+
+      counted_spans.each do |span|
+        tokens = span["tokens"] || {}
+        total_input += (tokens["input"] || 0)
+        total_output += (tokens["output"] || 0)
+        total_thinking += (tokens["thinking"] || 0)
+      end
+
+      # Extract agent info from root span attributes
+      attributes = root_span["attributes"] || {}
+      agent_class = attributes["agent.class"]
+      agent_action = attributes["agent.action"]
+
+      # Find any error message
+      error_span = spans.find { |s| s["status"] == STATUS_ERROR }
+      error_message = error_span&.dig("attributes", "error.message")
+
+      attrs = {
+        trace_id: trace["trace_id"],
+        service_name: trace["service_name"],
+        environment: trace["environment"],
+        timestamp: Time.parse(trace["timestamp"]),
+        spans: spans,
+        resource_attributes: trace["resource_attributes"],
+        sdk_info: sdk_info,
+        total_duration_ms: total_duration,
+        total_input_tokens: total_input,
+        total_output_tokens: total_output,
+        total_thinking_tokens: total_thinking,
+        status: root_span["status"] || STATUS_UNSET,
+        agent_class: agent_class,
+        agent_action: agent_action,
+        error_message: error_message
+      }
+
+      # Add account if in multi-tenant mode
+      attrs[:account] = account if ActionAgent.multi_tenant? && account
+
+      create!(attrs)
+    end
+
+    # Sums a span's token counts (used to decide which spans carry the
+    # authoritative token data during ingestion).
+    #
+    # @api private
+    def self.span_token_sum(span)
+      tokens = span["tokens"] || {}
+      tokens.fetch("input", 0).to_i + tokens.fetch("output", 0).to_i + tokens.fetch("thinking", 0).to_i
+    end
+
+    # Returns the root span of this trace.
+    #
+    # @return [Hash, nil] The root span or nil
+    def root_span
+      spans&.find { |s| s["parent_span_id"].nil? }
+    end
+
+    # Returns all LLM spans in this trace.
+    #
+    # @return [Array<Hash>] LLM spans
+    def llm_spans
+      spans&.select { |s| s["type"] == "llm" } || []
+    end
+
+    # Returns all tool call spans in this trace.
+    #
+    # @return [Array<Hash>] Tool spans
+    def tool_spans
+      spans&.select { |s| s["type"] == "tool" } || []
+    end
+
+    # Returns each tool call in this trace, normalized for display.
+    #
+    # Tool spans are tagged with their origin at instrumentation time
+    # (ActiveAgent::Telemetry::ToolOrigin), but traces ingested before that
+    # shipped — or sent by another SDK — only carry +tool.name+. Those are
+    # classified on read from the same naming convention, so a dashboard
+    # sees consistent attribution across old and new traces.
+    #
+    # @return [Array<Hash>] one entry per tool span with :name, :base_name,
+    #   :origin, :mcp_server, :duration_ms, :status, :error, :arguments and
+    #   :result
+    def tool_usage
+      tool_spans.map do |span|
+        attributes = span["attributes"] || {}
+        name = attributes["tool.name"] || span["name"].to_s.delete_prefix("tool.")
+        classification = classify_tool(name, attributes)
+
+        {
+          name: name,
+          base_name: attributes["tool.base_name"] || classification[:tool],
+          origin: attributes["tool.origin"] || classification[:origin],
+          mcp_server: attributes["tool.mcp_server"] || classification[:server],
+          duration_ms: span["duration_ms"],
+          status: span["status"],
+          error: attributes["error.message"],
+          arguments: attributes["tool.input.args"],
+          result: attributes["tool.output.result"]
+        }
+      end
+    end
+
+    # Returns the tools this trace's generation request OFFERED the
+    # provider, whether or not the model went on to call any of them.
+    #
+    # Instrumentation records the roster on the prompt span as
+    # +prompt.input.tools+ (name, description, parameter keys), which is
+    # the agent's declared tool surface for that generation. Reading it
+    # here is what lets a dashboard show a tool that exists but has never
+    # been invoked — a state that tool spans alone can't express.
+    #
+    # @return [Array<Hash>] entries with :name, :description, :parameters,
+    #   :origin and :mcp_server
+    def declared_tools
+      Array(tool_roster).filter_map do |tool|
+        next unless tool.is_a?(Hash)
+
+        name = (tool["name"] || tool[:name]).to_s
+        next if name.empty?
+
+        classification = ActiveAgent::Telemetry::ToolOrigin.classify(name)
+        {
+          name: name,
+          description: (tool["description"] || tool[:description]).presence,
+          parameters: normalize_parameters(tool["parameters"] || tool[:parameters]),
+          origin: classification[:origin],
+          mcp_server: classification[:server]
+        }
+      end
+    end
+
+    # Returns the distinct MCP servers this trace touched — both the ones
+    # it called and the ones it was merely offered.
+    #
+    # @return [Array<String>] server names, in first-seen order
+    def mcp_servers
+      (tool_usage.filter_map { |tool| tool[:mcp_server] } +
+        declared_tools.filter_map { |tool| tool[:mcp_server] }).uniq
+    end
+
+    # Returns total token count.
+    #
+    # @return [Integer] Total tokens used
+    def total_tokens
+      (total_input_tokens || 0) + (total_output_tokens || 0) + (total_thinking_tokens || 0)
+    end
+
+    # Returns whether this trace had an error.
+    #
+    # @return [Boolean]
+    def error?
+      status == STATUS_ERROR
+    end
+
+    # Returns display name for the trace.
+    #
+    # @return [String] Display name (e.g., "WeatherAgent.forecast")
+    def display_name
+      if agent_class && agent_action
+        "#{agent_class}.#{agent_action}"
+      elsif agent_class
+        agent_class
+      else
+        trace_id&.first(8)
+      end
+    end
+
+    # Returns formatted duration.
+    #
+    # @return [String] Duration in ms or s
+    def formatted_duration
+      return "—" unless total_duration_ms
+
+      if total_duration_ms >= 1000
+        "#{(total_duration_ms / 1000.0).round(2)}s"
+      else
+        "#{total_duration_ms.round(0)}ms"
+      end
+    end
+
+    # Returns formatted token count.
+    #
+    # @return [String] Token count with K suffix for large numbers
+    def formatted_tokens
+      count = total_tokens
+      return "0" if count.zero?
+
+      if count >= 1000
+        "#{(count / 1000.0).round(1)}K"
+      else
+        count.to_s
+      end
+    end
+
+    # Returns the provider used (from LLM spans).
+    #
+    # @return [String, nil] Provider name
+    def provider
+      llm_span = llm_spans.first
+      return nil unless llm_span
+
+      llm_span.dig("attributes", "llm.provider")
+    end
+
+    # Returns the model used (from LLM spans).
+    #
+    # @return [String, nil] Model name
+    def model
+      llm_span = llm_spans.first
+      return nil unless llm_span
+
+      llm_span.dig("attributes", "llm.model")
+    end
+
+    private
+
+    # The offered roster, as stored. Instrumentation writes JSON onto the
+    # prompt span; +llm.tools+ is accepted as an alias because some SDK
+    # versions put the roster on the llm span instead, and a payload that
+    # arrived already decoded is passed straight through.
+    def tool_roster
+      raw = spans.to_a.filter_map do |span|
+        attributes = span["attributes"] || {}
+        attributes["prompt.input.tools"].presence || attributes["llm.tools"].presence
+      end.first
+      return nil if raw.blank?
+      return raw unless raw.is_a?(String)
+
+      JSON.parse(raw)
+    rescue JSON::ParserError
+      nil
+    end
+
+    # The roster records parameters as a name list, but a raw JSON Schema
+    # arrives instead when an SDK forwards tool definitions verbatim.
+    def normalize_parameters(parameters)
+      return [] if parameters.blank?
+      return parameters.map(&:to_s) if parameters.is_a?(Array)
+
+      if parameters.is_a?(Hash)
+        properties = parameters["properties"] || parameters[:properties]
+        return properties.keys.map(&:to_s) if properties.is_a?(Hash)
+      end
+
+      []
+    end
+
+    # Recovers a tool's origin for traces that predate origin tagging.
+    # Prefers an explicit server attribute when the SDK sent one, then
+    # falls back to the shared name-convention classifier.
+    def classify_tool(name, attributes)
+      explicit = attributes["mcp.server"] || attributes["tool.server"]
+      return { origin: "mcp", server: explicit, tool: name } if explicit.present?
+
+      ActiveAgent::Telemetry::ToolOrigin.classify(name)
+    end
+  end
+end