actionagent 0.0.0 → 1.2.0

data/app/models/action_agent/agent.rb

@@ -0,0 +1,343 @@
+# frozen_string_literal: true
+
+module ActionAgent
+  class Agent < ApplicationRecord
+    include Ownable
+    owned_by :user, :account
+
+    has_many :agent_versions, dependent: :destroy
+    has_many :agent_runs, dependent: :destroy
+    has_many :evaluations, dependent: :destroy
+    has_many :agent_memories, as: :memorable, dependent: :destroy
+
+    # Polymorphic rows (agent_memories, agent_contexts) store this string.
+    # A host app that grew these tables under its own Agent constant keeps
+    # its existing rows readable by setting agent_polymorphic_name.
+    def self.polymorphic_name
+      ActionAgent.agent_polymorphic_name || super
+    end
+
+    # Validations
+    validates :name, presence: true, length: { minimum: 2, maximum: 100 }
+    validates :slug, presence: true, format: { with: /\A[a-z0-9\-_]+\z/ }
+    # Slugs are unique per owner. Which column that means depends on the
+    # configured mode, so it is resolved at validation time rather than
+    # baked into a uniqueness scope when the class loads.
+    validate :slug_unique_within_owner
+    validates :provider, presence: true
+    validates :model, presence: true
+    validate :validate_action_prompts
+
+    # Status enum
+    # `observed` agents were discovered from reported telemetry rather than
+    # authored here. They can't be executed by the platform — we can't push
+    # instructions into someone else's app — so they're read-only until forked.
+    enum :status, { draft: 0, active: 1, archived: 2, observed: 3 }
+
+    scope :observed_agents, -> { where(status: :observed) }
+    scope :authored, -> { where.not(status: :observed) }
+
+    # Callbacks
+    before_validation :generate_slug, on: :create
+    after_create :create_initial_version
+    after_update :create_version_on_config_change, if: :configuration_changed?
+
+    # Scopes
+    scope :active_agents, -> { where(status: :active) }
+    scope :by_provider, ->(provider) { where(provider: provider) }
+    # jsonb containment on PostgreSQL; a substring match on the serialized
+    # array everywhere else. The fallback can over-match a tool whose name
+    # is a prefix of another, so the JSON quoting is kept in the pattern.
+    scope :with_tool, ->(tool) {
+      if postgres?
+        # Cast both sides: @> is a jsonb operator, and a host app mounting
+        # the engine over its own pre-existing tables may have declared the
+        # column as json.
+        where("tools::jsonb @> ?::jsonb", [ tool ].to_json)
+      else
+        where("tools LIKE ?", "%\"#{tool}\"%")
+      end
+    }
+
+    # Available presets matching AgentAvatar component
+    PRESET_TYPES = %w[
+      terminal webDeveloper documentAnalysis writing translation
+      playwright research imageAnalysis computerUse productDesign
+    ].freeze
+
+    # Available instruction sets
+    INSTRUCTION_SETS = %w[
+      github ruby rails aws gcp python typescript docker kubernetes
+    ].freeze
+
+    # Available tools/MCPs
+    AVAILABLE_TOOLS = %w[
+      terminal playwright filesystem code database slack fetch search edit translate memory agents
+    ].freeze
+
+    # Available providers
+    PROVIDERS = %w[openai anthropic ollama openrouter].freeze
+
+    # The ActiveAgent class name this agent's runs are recorded under — the
+    # correlation key between platform Agent records and telemetry traces
+    # (TelemetryTrace#agent_class) and solid_agent contexts.
+    def telemetry_agent_class
+      base = agent_class_name.presence || name.parameterize(separator: "_").camelize
+      base.end_with?("Agent") ? base : "#{base}Agent"
+    end
+
+    # The agent's long-term memory (solid_agent HasMemory contract) — the
+    # summary list its runs read/write via the memory tools.
+    def memory
+      AgentMemory.for(self)
+    end
+
+    # The default action every agent has; uses the base instructions alone.
+    DEFAULT_ACTION = "ask"
+
+    # All invokable action names: the default plus each named action prompt.
+    def available_actions
+      [ DEFAULT_ACTION ] + Array(action_prompts).filter_map { |ap| ap["name"].presence }
+    end
+
+    def action_prompt_for(action_name)
+      Array(action_prompts).find { |ap| ap["name"] == action_name.to_s }
+    end
+
+    # The system instructions an action executes under: named actions stack
+    # their prompt below the agent's base instructions; the default action
+    # uses the base instructions alone.
+    def composed_instructions_for(action_name)
+      action = action_prompt_for(action_name)
+      [ instructions, action&.dig("prompt") ].map(&:presence).compact.join("\n\n").presence
+    end
+
+    # Returns the configuration as a hash for versioning
+    def configuration_snapshot
+      {
+        name: name,
+        description: description,
+        provider: provider,
+        model: model,
+        instructions: instructions,
+        action_prompts: action_prompts,
+        preset_type: preset_type,
+        appearance: appearance,
+        instruction_sets: instruction_sets,
+        tools: tools,
+        mcp_servers: mcp_servers,
+        model_config: model_config,
+        response_format: response_format
+      }
+    end
+
+    # Restore from a version
+    def restore_from_version!(version)
+      config = version.configuration_snapshot
+      update!(
+        instructions: config["instructions"],
+        action_prompts: config["action_prompts"] || [],
+        preset_type: config["preset_type"],
+        appearance: config["appearance"],
+        instruction_sets: config["instruction_sets"],
+        tools: config["tools"],
+        mcp_servers: config["mcp_servers"],
+        model_config: config["model_config"],
+        response_format: config["response_format"]
+      )
+    end
+
+    # Get the latest version
+    def latest_version
+      agent_versions.order(version_number: :desc).first
+    end
+
+    # Maps each historical instructions digest to the first version that
+    # introduced it ("v3"), so run cohorts can label instruction changes with
+    # real agent versions instead of raw hashes.
+    def instructions_digest_versions
+      agent_versions.order(:version_number).each_with_object({}) do |version, map|
+        snapshot = version.configuration_snapshot
+        base = snapshot["instructions"]
+        label = "v#{version.version_number}"
+
+        if base.present?
+          map[Digest::SHA256.hexdigest(base).first(8)] ||= label
+        end
+
+        # Named actions run under composed instructions (base + action
+        # prompt), so their runs carry a different digest per action.
+        Array(snapshot["action_prompts"]).each do |action|
+          composed = [ base, action["prompt"] ].map(&:presence).compact.join("\n\n")
+          next if composed.blank?
+
+          map[Digest::SHA256.hexdigest(composed).first(8)] ||= label
+        end
+      end
+    end
+
+    # Get version count
+    def version_count
+      agent_versions.count
+    end
+
+    # Generate Ruby agent class code
+    def to_agent_class_code
+      <<~RUBY
+        class #{agent_class_name || name.camelize}Agent < ApplicationAgent
+          generate_with :#{provider}, model: "#{model}"#{model_config_code}
+
+          def perform
+            prompt#{instructions_code}
+          end
+        end
+      RUBY
+    end
+
+    # Execute a run with this agent
+    def execute(input_prompt, action: nil, **params)
+      run = agent_runs.create!(
+        input_prompt: input_prompt,
+        action_name: normalized_action(action),
+        input_params: params,
+        status: :pending,
+        trace_id: SecureRandom.uuid
+      )
+
+      # Queue the execution job
+      AgentExecutionJob.perform_later(run.id)
+
+      run
+    end
+
+    # Quick test execution (synchronous)
+    def test_execute(input_prompt, action: nil, **params)
+      run = agent_runs.create!(
+        input_prompt: input_prompt,
+        action_name: normalized_action(action),
+        input_params: params,
+        status: :running,
+        trace_id: SecureRandom.uuid,
+        started_at: Time.current
+      )
+
+      begin
+        # Build and execute the agent
+        result = AgentExecutionService.call(self, 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)
+        )
+      rescue => e
+        run.update!(
+          status: :failed,
+          completed_at: Time.current,
+          error_message: e.message,
+          error_backtrace: e.backtrace&.first(10)&.join("\n")
+        )
+      end
+
+      run
+    end
+
+    private
+
+    def slug_unique_within_owner
+      return if slug.blank?
+
+      siblings = self.class.for_owner(owner)
+      siblings = siblings.where.not(id: id) if persisted?
+      errors.add(:slug, "has already been taken") if siblings.exists?(slug: slug)
+    end
+
+    def generate_slug
+      return if slug.present?
+
+      base_slug = name.to_s.parameterize
+      self.slug = base_slug
+
+      # Checked globally rather than per owner: a host app may have a global
+      # unique index on slug (ours does), and suffixing costs one query.
+      counter = 1
+      while self.class.exists?(slug: slug)
+        self.slug = "#{base_slug}-#{counter}"
+        counter += 1
+      end
+    end
+
+    def create_initial_version
+      agent_versions.create!(
+        version_number: 1,
+        change_summary: "Initial creation",
+        configuration_snapshot: configuration_snapshot
+      )
+    end
+
+    VERSIONED_FIELDS = %w[
+      instructions action_prompts preset_type appearance instruction_sets
+      tools mcp_servers model_config response_format
+    ].freeze
+
+    def configuration_changed?
+      saved_changes.keys.any? { |key| VERSIONED_FIELDS.include?(key) }
+    end
+
+    def create_version_on_config_change
+      next_version = (latest_version&.version_number || 0) + 1
+      changed_fields = saved_changes.keys.select { |key| VERSIONED_FIELDS.include?(key) }
+
+      agent_versions.create!(
+        version_number: next_version,
+        change_summary: "Updated: #{changed_fields.join(', ')}",
+        configuration_snapshot: configuration_snapshot
+      )
+    end
+
+    # Unknown action names fall back to the default rather than failing the
+    # run — an action can be renamed between enqueue and execution.
+    def normalized_action(action)
+      action = action.to_s.presence
+      action && available_actions.include?(action) ? action : nil
+    end
+
+    def validate_action_prompts
+      return if action_prompts.blank?
+
+      unless action_prompts.is_a?(Array) && action_prompts.all? { |ap| ap.is_a?(Hash) }
+        errors.add(:action_prompts, "must be a list of action definitions")
+        return
+      end
+
+      names = action_prompts.map { |ap| ap["name"].to_s }
+      names.each do |action_name|
+        unless action_name.match?(/\A[a-z][a-z0-9_]*\z/)
+          errors.add(:action_prompts, "action name '#{action_name}' must be snake_case")
+        end
+        if action_name == DEFAULT_ACTION
+          errors.add(:action_prompts, "'#{DEFAULT_ACTION}' is the built-in default action")
+        end
+      end
+      errors.add(:action_prompts, "action names must be unique") if names.uniq.size != names.size
+    end
+
+    def model_config_code
+      return "" if model_config.blank?
+
+      configs = model_config.map { |k, v| "#{k}: #{v.inspect}" }.join(", ")
+      ", #{configs}"
+    end
+
+    def instructions_code
+      return "" if instructions.blank?
+
+      "\n    prompt instructions: <<~INSTRUCTIONS\n      #{instructions.gsub("\n", "\n      ")}\n    INSTRUCTIONS"
+    end
+  end
+end

data/app/models/action_agent/agent_context.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module ActionAgent
+  # Conversation context persisted by SolidAgent::HasContext — one row per
+  # (contextable, agent, action). On this platform the contextable is the
+  # dashboard Agent record, so a context is that agent's interaction stream.
+  #
+  # Based on the solid_agent install generator's AgentContext, extended with
+  # record_generation_with_provenance! (the concern's duck-typed extension
+  # point) so each generation carries the telemetry trace_id and provenance.
+  class AgentContext < ApplicationRecord
+    belongs_to :contextable, polymorphic: true, optional: true
+    has_many :messages, class_name: "AgentMessage", dependent: :destroy
+    has_many :generations, class_name: "AgentGeneration", dependent: :destroy
+
+    validates :agent_name, presence: true
+    validates :action_name, presence: true
+
+    scope :recent, -> { order(updated_at: :desc) }
+    scope :for_agent, ->(name) { where(agent_name: name) }
+    scope :for_action, ->(name) { where(action_name: name) }
+    scope :with_trace, ->(trace_id) { where(trace_id: trace_id) }
+    scope :for_agents, ->(agents) { where(contextable_type: Agent.polymorphic_name, contextable_id: agents.select(:id)) }
+
+    # Records a generation response and updates token counts.
+    #
+    # Defensive against response objects that don't expose provider/duration
+    # (activeagent 1.0.3 responses don't) — solid_agent's stock template would
+    # raise (and silently drop the generation) on those.
+    def record_generation!(response, extra_attributes = {})
+      usage = response.respond_to?(:usage) ? response.usage : nil
+
+      generation = generations.create!({
+        content: response.message&.content,
+        model: value_if_responds(response, :model),
+        provider: value_if_responds(response, :provider),
+        finish_reason: value_if_responds(response, :finish_reason),
+        input_tokens: usage&.input_tokens || 0,
+        output_tokens: usage&.output_tokens || 0,
+        cached_tokens: value_if_responds(usage, :cached_tokens) || 0,
+        reasoning_tokens: value_if_responds(usage, :reasoning_tokens) || 0,
+        tool_calls: extract_tool_calls(response),
+        raw_response: value_if_responds(response, :raw_response),
+        duration_seconds: extract_duration_seconds(response, usage)
+      }.merge(extra_attributes))
+
+      increment!(:total_input_tokens, generation.input_tokens)
+      increment!(:total_output_tokens, generation.output_tokens)
+
+      add_assistant_message(response.message&.content, metadata: { "tool_calls" => generation.tool_calls })
+
+      generation
+    end
+
+    # Called by SolidAgent::HasContext when defined: persists the generation
+    # together with its provenance hash and the telemetry trace_id, so
+    # conversation records join to active_agent_telemetry_traces.
+    def record_generation_with_provenance!(response, provenance)
+      provenance = (provenance || {}).deep_stringify_keys
+
+      record_generation!(
+        response,
+        trace_id: provenance["trace_id"],
+        provenance: provenance
+      )
+    end
+
+    def add_user_message(content, **attributes)
+      messages.create!(role: "user", content: content, **attributes)
+    end
+
+    def add_assistant_message(content, **attributes)
+      messages.create!(role: "assistant", content: content, **attributes)
+    end
+
+    def add_system_message(content)
+      messages.create!(role: "system", content: content)
+    end
+
+    def add_tool_message(tool_call_id:, tool_name:, result:, arguments: nil, duration_ms: nil)
+      messages.create!(
+        role: "tool",
+        tool_call_id: tool_call_id,
+        tool_name: tool_name,
+        tool_result: result,
+        tool_arguments: arguments.presence || {},
+        metadata: duration_ms ? { "duration_ms" => duration_ms } : {},
+        content: result.is_a?(String) ? result : result.to_json
+      )
+    end
+
+    def total_tokens
+      total_input_tokens + total_output_tokens
+    end
+
+    def input_params
+      options&.dig("input_params") || {}
+    end
+
+    private
+
+    def value_if_responds(response, method)
+      response.respond_to?(method) ? response.public_send(method) : nil
+    end
+
+    def extract_duration_seconds(response, usage)
+      return response.duration if response.respond_to?(:duration) && response.duration
+
+      duration_ms = usage&.respond_to?(:duration_ms) ? usage.duration_ms : nil
+      duration_ms ? duration_ms / 1000.0 : nil
+    end
+
+    def extract_tool_calls(response)
+      message = response.message
+      return [] unless message.respond_to?(:tool_calls)
+
+      tool_calls = message.tool_calls
+      return [] if tool_calls.blank?
+
+      tool_calls.map do |tc|
+        {
+          id: value_if_responds(tc, :id),
+          name: value_if_responds(tc, :name),
+          arguments: value_if_responds(tc, :arguments)
+        }
+      end
+    end
+  end
+end

data/app/models/action_agent/agent_generation.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module ActionAgent
+  # One LLM generation call within an agent conversation context. From the
+  # solid_agent install generator, extended with trace_id (joins to
+  # active_agent_telemetry_traces) and the SolidAgent provenance hash.
+  class AgentGeneration < ApplicationRecord
+    belongs_to :agent_context
+
+    scope :recent, -> { order(created_at: :desc) }
+    scope :by_model, ->(model) { where(model: model) }
+    scope :with_tool_calls, -> { where(json_array_not_empty_sql(:tool_calls)) }
+    scope :with_trace, ->(trace_id) { where(trace_id: trace_id) }
+
+    def total_tokens
+      input_tokens + output_tokens
+    end
+
+    def has_tool_calls?
+      tool_calls.present? && tool_calls.any?
+    end
+
+    def completed?
+      finish_reason == "stop"
+    end
+
+    def truncated?
+      finish_reason == "length"
+    end
+
+    # Provider prompt-cache hit on this generation?
+    def cache_hit?
+      cached_tokens.to_i.positive?
+    end
+
+    # Extended thinking captured?
+    def thinking?
+      reasoning_tokens.to_i.positive?
+    end
+
+    # The telemetry trace this generation belongs to, when recorded.
+    def telemetry_trace
+      return nil if trace_id.blank?
+
+      ActionAgent.trace_model.find_by(trace_id: trace_id)
+    end
+  end
+end

data/app/models/action_agent/agent_memory.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module ActionAgent
+  # Agent-curated long-term memory for a subject record (solid_agent
+  # HasMemory contract). On this platform the memorable is usually the
+  # dashboard Agent record; agents write/read it through the save_memory /
+  # recall_memory tools during generation runs.
+  #
+  # Memory is scoped to (memorable, scope) — not to an agent class — so any
+  # agent operating on the same subject shares it, making it a handoff
+  # channel between agents. Entry source_agent records who wrote each note.
+  class AgentMemory < ApplicationRecord
+    DEFAULT_SCOPE = "default"
+
+    belongs_to :memorable, polymorphic: true, optional: true
+    has_many :entries, class_name: "AgentMemoryEntry", dependent: :destroy
+
+    validates :scope, presence: true
+
+    def self.for(memorable, scope: DEFAULT_SCOPE)
+      find_or_create_by!(memorable: memorable, scope: scope.to_s)
+    end
+
+    def remember(content, source_agent: nil, category: nil)
+      entries.create!(content: content, source_agent: source_agent, category: category)
+    end
+
+    def recall(limit: 20, category: nil)
+      scope = entries.order(created_at: :desc)
+      scope = scope.where(category: category) if category.present?
+      scope.limit(limit || 20).to_a
+    end
+
+    def summary_list
+      entries.order(:created_at).pluck(:content)
+    end
+
+    # Formatted block suitable for injecting into another agent's
+    # instructions when handing a subject off.
+    def to_prompt
+      notes = entries.order(:created_at).map do |entry|
+        source = entry.source_agent.present? ? " (#{entry.source_agent})" : ""
+        "- #{entry.content}#{source}"
+      end
+      return "" if notes.empty?
+
+      "Memory notes for this subject:\n#{notes.join("\n")}"
+    end
+  end
+end

data/app/models/action_agent/agent_memory_entry.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module ActionAgent
+  # One agent-authored summary note in an AgentMemory.
+  class AgentMemoryEntry < ApplicationRecord
+    belongs_to :agent_memory
+
+    validates :content, presence: true
+
+    scope :chronological, -> { order(:created_at) }
+    scope :by_category, ->(category) { where(category: category) }
+    scope :from_agent, ->(agent_name) { where(source_agent: agent_name) }
+  end
+end

data/app/models/action_agent/agent_message.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module ActionAgent
+  # A single message in an agent conversation context (user, assistant,
+  # system, or tool). From the solid_agent install generator; the provenance
+  # and content_checksum columns are populated automatically by
+  # SolidAgent::HasContext.
+  class AgentMessage < ApplicationRecord
+    belongs_to :agent_context
+
+    validates :role, presence: true, inclusion: { in: %w[user assistant system tool] }
+
+    scope :by_role, ->(role) { where(role: role) }
+    scope :user_messages, -> { by_role("user") }
+    scope :assistant_messages, -> { by_role("assistant") }
+    scope :chronological, -> { order(created_at: :asc) }
+
+    # Converts the message to a hash format for ActiveAgent prompts
+    def to_message_hash
+      hash = { role: role, content: content }
+      hash[:tool_calls] = tool_calls_data if role == "assistant" && tool_calls_data.present?
+
+      if role == "tool"
+        hash[:tool_call_id] = tool_call_id
+        hash[:name] = tool_name
+      end
+
+      hash
+    end
+
+    def tool_calls_data
+      metadata&.dig("tool_calls") || []
+    end
+
+    def tool_call?
+      role == "assistant" && tool_calls_data.present?
+    end
+
+    def tool_result?
+      role == "tool"
+    end
+  end
+end