actionagent 1.8.1 → 1.9.0

data/lib/generators/action_agent/install_generator.rb

@@ -19,6 +19,37 @@ module ActionAgent
 
     source_root File.expand_path("templates", __dir__)
 
+    # A numbered migration template is templates/migrations/NNN_<name>.rb.erb,
+    # emitted as db/migrate/<timestamp>_<name>.rb: "015_add_widget_scope.rb.erb"
+    # becomes "<timestamp>_add_widget_scope.rb". A migration added to the
+    # engine ships this way, as one new file and no generator change. The
+    # templates are emitted after every other dashboard migration, in NNN
+    # order, so a later number may alter what an earlier one created. A
+    # template is skipped when db/migrate already holds a migration of its
+    # name. A traces-only install skips them all.
+    NUMBERED_MIGRATION = /\A\d{3}_(?<name>[a-z0-9_]+)\.rb\.erb\z/
+
+    class << self
+      # Where the numbered migration templates live.
+      attr_writer :numbered_migrations_path
+
+      def numbered_migrations_path
+        @numbered_migrations_path || File.expand_path("templates/migrations", __dir__)
+      end
+
+      # The numbered migration templates, in the order they are emitted, as
+      # [template path, migration name] pairs. Files whose names do not
+      # follow the convention are left out.
+      def numbered_migrations
+        Dir.children(numbered_migrations_path).sort.filter_map do |file|
+          match = NUMBERED_MIGRATION.match(file)
+          [ File.join(numbered_migrations_path, file), match[:name] ] if match
+        end
+      rescue Errno::ENOENT
+        []
+      end
+    end
+
     desc "Installs the ActiveAgent Dashboard with telemetry storage"
 
     class_option :multi_tenant, type: :boolean, default: false,
@@ -138,6 +169,12 @@ module ActionAgent
       unless existing_migration?("add_code_session_runner")
         migration_template("add_code_session_runner.rb.erb", "db/migrate/add_code_session_runner.rb")
       end
+
+      self.class.numbered_migrations.each do |template, name|
+        next if existing_migration?(name)
+
+        migration_template(template, "db/migrate/#{name}.rb")
+      end
     end
 
     def add_route

data/lib/generators/action_agent/templates/action_agent.rb.erb

@@ -79,6 +79,95 @@ ActionAgent.configure do |config|
   # With an owner model configured, an owner that does not resolve sees
   # nothing rather than everything. An empty dashboard for a signed-in user
   # means the resolver above returned nil.
+  #
+  # Each model is owned by one class: agents, sandboxes, recordings and code
+  # sessions name the user first, keys and connections the account. With
+  # both classes configured, the dashboard still resolves the account as the
+  # owner, so a platform that scopes everything by account re-declares the
+  # user-first models from `to_prepare` and maps a user to its account:
+  #
+  # Rails.application.config.to_prepare do
+  #   [ActionAgent::Agent, ActionAgent::SandboxSession,
+  #    ActionAgent::SessionRecording, ActionAgent::CodeSession].each do |model|
+  #     model.owned_by :account, :user
+  #   end
+  # end
+  # config.tenant_resolver = ->(owner) { owner.is_a?(User) ? owner.account : owner }
+  #
+  # An owner of another class than the one a model is owned by reads nothing
+  # and is refused as a writer, so leaving this out shows an empty dashboard
+  # rather than another tenant's records.
+
+  # ==========================================================================
+  # Permissions
+  # ==========================================================================
+  #
+  # Who may perform the dashboard's privileged actions: storing provider
+  # credentials (:manage_credentials), connecting GitHub (:manage_github),
+  # creating and revoking API keys (:manage_api_keys), answering a paused
+  # run's request for input (:answer_input_request), and the rest of
+  # ActionAgent::PERMISSION_ACTIONS. Called with the signed-in user, the
+  # action and the record it applies to; true allows, false denies with a
+  # 403. Unset, anyone who passes authentication may do all of them. With
+  # multi_tenant on, that is every member of every tenant, and the engine
+  # logs a warning at boot until a checker is set.
+  #
+  # An exception from the checker denies. In multi-tenant mode a nil answer,
+  # or no signed-in user, also denies; in single-tenant mode a nil answer
+  # allows.
+  #
+  # config.permission_checker = ->(user, action, subject) {
+  #   user.present? && user.admin?
+  # }
+
+  # ==========================================================================
+  # Provider keys and members
+  # ===================================================================
+  #
+  # Agent runs, the evaluation judge and the assistant use the account's
+  # provider keys (Settings -> API Keys, or the Organization page) before
+  # config/active_agent.yml. With :personal_override, each member may also
+  # save a personal key per provider, which the runs they start use first.
+  # A personal key sends the organization's agent traffic to that member's
+  # own provider account, so it is off by default. It needs account_class;
+  # the judge, sandboxes, Claude Code and Codex always use the account's keys.
+  # A personal Ollama host decides where the server sends requests, so
+  # saving or testing one asks the permission_checker above for
+  # :manage_credentials, with the personal key (subject.personal?) as the
+  # subject.
+  #
+  # config.provider_key_scope = :personal_override
+  #
+  # Credentials your app keeps elsewhere, tried after a personal key and
+  # before the account's stored key. Declare actor: to learn who is acting
+  # (nil for the judge and unattributed runs). With multi_tenant on, a
+  # resolver that raises fails the run rather than falling back to
+  # config/active_agent.yml. If it reads the provider_keys table, keep it
+  # to organization rows (ActionAgent::ProviderKey.for_owner does).
+  #
+  # config.provider_credentials_resolver = ->(owner, provider, actor: nil) {
+  #   owner.provider_credentials_for(provider)
+  # }
+  #
+  # The Organization page's Team Members table, as
+  # [{ id:, name:, email:, role: }], and where "+ Invite Member" links. Both
+  # unset, the table lists the signed-in user and the button is hidden.
+  #
+  # config.members_resolver = ->(account) {
+  #   account.members.map { |user| { id: user.id, name: user.name, email: user.email, role: user.role } }
+  # }
+  # config.member_invite_url = "/team/invitations/new"
+
+  # ==========================================================================
+  # Input requests
+  # ==========================================================================
+  #
+  # How long a paused run's request for input waits for an answer. A later
+  # answer is refused with a 409, and the run fails. Schedule
+  # ActionAgent::InputRequestExpiryJob to fail the runs whose requests
+  # nobody answers or looks at.
+  #
+  # config.input_request_ttl = 1.day
 
   # ==========================================================================
   # Host integration
@@ -106,6 +195,63 @@ ActionAgent.configure do |config|
   #
   # config.assistant_enabled = true
 
+  # ==========================================================================
+  # GitHub
+  # ===================================================================
+
+  #
+  # Checkout sandboxes clone repositories chosen in Settings -> Integrations.
+  # Through a GitHub App, each checkout gets a one-hour token limited to its
+  # one repository. Settings -> Integrations -> Create GitHub App registers
+  # one for you and shows these values once; otherwise register the App with
+  # "Request user authorization (OAuth) during installation" and "Redirect on
+  # update" turned on and the callback URL
+  # <mount>/api/github_installations/callback. Each setting falls back to its
+  # GITHUB_APP_* environment variable.
+  #
+  # config.github_app_id = Rails.application.credentials.dig(:github_app, :id)
+  # config.github_app_slug = Rails.application.credentials.dig(:github_app, :slug)
+  # config.github_app_client_id = Rails.application.credentials.dig(:github_app, :client_id)
+  # config.github_app_client_secret = Rails.application.credentials.dig(:github_app, :client_secret)
+  # config.github_app_private_key = Rails.application.credentials.dig(:github_app, :private_key)
+  #
+  # Or an OAuth App, connected per owner with the callback URL
+  # <mount>/api/github_connection/callback (GITHUB_CLIENT_ID and
+  # GITHUB_CLIENT_SECRET when unset).
+  #
+  # config.github_client_id = Rails.application.credentials.dig(:github, :client_id)
+  # config.github_client_secret = Rails.application.credentials.dig(:github, :client_secret)
+
+  # ==========================================================================
+  # Recording the Run Agent workbench
+  # ==========================================================================
+  #
+  # While the Run Agent workbench has a conversation open, the dashboard
+  # records the page with rrweb, and the recording replays as the
+  # conversation's browser lane. Field values are masked, elements marked
+  # data-aa-secret and hidden inputs are left out, and the owner's stored
+  # credentials are masked in every batch; what the page shows otherwise, the
+  # conversation included, is recorded as shown. Set it to false to record
+  # nothing: conversations still replay from their messages, model calls and
+  # tool calls.
+  #
+  # config.capture_dashboard_sessions = false
+
+  # ==========================================================================
+  # Active Storage
+  # ==========================================================================
+  #
+  # The dashboard attaches files in a few places: the files uploaded with a
+  # run, a session recording's snapshots and oversized event payloads, and a
+  # scenario catalog's YAML. By default (:auto) it uses Active Storage when
+  # this app has it loaded and migrated, and otherwise keeps the
+  # metadata-only form of each feature. true requires it (boot raises
+  # without it); false never attaches. The service names one from
+  # config/storage.yml; unset, attachments use the app's default service.
+  #
+  # config.active_storage = :auto
+  # config.active_storage_service = :recordings
+
   # ==========================================================================
   # Sandboxes
   # ==========================================================================
@@ -150,6 +296,18 @@ ActionAgent.configure do |config|
   #
   # config.claude_code_auth = :local_login
   #
+  # :sandbox_login adds the same subscription sign-in flow to Settings ->
+  # Integrations and evaluation fix cards. Requires current_user_resolver
+  # and an unmodified Claude Code CLI. Credentials stay in one sandbox's
+  # private CLAUDE_CONFIG_DIR, outside its checkout; they are never imported
+  # into ProviderKey. The account API key remains the fallback.
+  # config.claude_code_auth = :sandbox_login
+  # config.claude_code_login_timeout = 300
+  # Remote backends must implement all four login verbs and refresh_runtime.
+  # Keep hosted login disabled until the operator has reviewed Anthropic's
+  # current commercial hosting requirements and configured tenant isolation.
+  # config.claude_code_hosted_login_enabled = false
+  #
   # Expired sandboxes are stopped by `bin/rails action_agent:sandbox:reap`.
   # Schedule it every few minutes.
 

data/lib/generators/action_agent/templates/migrations/015_add_provider_key_scope.rb.erb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+# Gives provider keys a scope: "organization" for the key an account shares,
+# "user:<id>" for one member's own key. The unique index on
+# (account_id, scope_key, provider) keeps one organization key per provider
+# and one personal key per member and provider. set_by_id names the user who
+# last saved a key from the dashboard.
+#
+# Existing rows become organization rows. An install whose rows break the
+# new index (two keys for one account and provider) stops here and lists
+# them, because only one of each pair can stay and this migration does not
+# choose. Guarded, so it is safe to re-run once they are resolved.
+class AddProviderKeyScope < ActiveRecord::Migration<%= migration_version %>
+  ORGANIZATION = "organization"
+
+  def up
+    return unless table_exists?(table)
+
+    refuse_duplicates!
+    add_column table, :scope_key, :string, null: false, default: ORGANIZATION unless column_exists?(table, :scope_key)
+    add_column table, :set_by_id, :bigint unless column_exists?(table, :set_by_id)
+    add_index table, %i[account_id scope_key provider], unique: true, name: index_name unless index_name_exists?(table, index_name)
+  end
+
+  # Refused while personal keys exist: without scope_key they would read as
+  # the organization's keys.
+  def down
+    return unless table_exists?(table)
+
+    if column_exists?(table, :scope_key)
+      personal = select_values("SELECT id FROM #{quoted_table} WHERE scope_key <> #{connection.quote(ORGANIZATION)} ORDER BY id")
+      if personal.any?
+        raise ActiveRecord::IrreversibleMigration,
+              "#{table} holds personal keys (ids #{personal.join(', ')}). Delete them before rolling back."
+      end
+    end
+
+    remove_index table, name: index_name if index_name_exists?(table, index_name)
+    remove_column table, :set_by_id if column_exists?(table, :set_by_id)
+    remove_column table, :scope_key if column_exists?(table, :scope_key)
+  end
+
+  private
+
+  def refuse_duplicates!
+    scoped = column_exists?(table, :scope_key)
+    columns = scoped ? "id, account_id, provider, scope_key" : "id, account_id, provider"
+    rows = select_rows("SELECT #{columns} FROM #{quoted_table} WHERE account_id IS NOT NULL ORDER BY id")
+    groups = rows.group_by { |(_id, account_id, provider, scope_key)| [ account_id, provider, scope_key || ORGANIZATION ] }
+    duplicates = groups.select { |_key, members| members.size > 1 }
+    return if duplicates.empty?
+
+    listed = duplicates.map do |(account_id, provider, scope_key), members|
+      "account_id #{account_id}, provider #{provider}, scope #{scope_key}: ids #{members.map(&:first).join(', ')}"
+    end
+    raise ActiveRecord::MigrationError,
+          "#{table} holds more than one key for the same account, provider and scope. Keep one of each and " \
+          "delete the rest, then run the migration again:\n  #{listed.join("\n  ")}"
+  end
+
+  def table
+    "#{ActionAgent.table_name_prefix}provider_keys"
+  end
+
+  def quoted_table
+    connection.quote_table_name(table)
+  end
+
+  def index_name
+    "index_#{table}_on_scope"
+  end
+end

data/lib/generators/action_agent/templates/migrations/016_create_active_agent_input_requests.rb.erb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+# Input requests: a question a paused run puts to a person, its answer, and
+# the checkpoint the run resumes from. Also adds the list of tools an agent
+# runs only after a person approves the call.
+#
+# Table names follow ActionAgent.table_name_prefix, and JSON columns are
+# jsonb on PostgreSQL and json elsewhere, the same way as
+# create_active_agent_dashboard_tables.
+class CreateActiveAgentInputRequests < ActiveRecord::Migration<%= migration_version %>
+  def change
+    prefix = ActionAgent.table_name_prefix
+
+    create_table "#{prefix}input_requests" do |t|
+      t.string :subject_type, null: false
+      t.bigint :subject_id, null: false
+      # Shared by the requests one pause raised.
+      t.string :pause_key, null: false
+      t.string :kind, null: false
+      t.text :prompt, null: false
+      t.column :options, json_type
+      t.column :answer_schema, json_type
+      t.string :tool_call_id
+      t.string :tool_name
+      # The paused call's arguments, kept for a confirm request only.
+      t.column :arguments, json_type
+      t.integer :status, default: 0, null: false
+      # Encrypted at rest (text: ciphertext is longer than the value).
+      t.text :answer, **long_text
+      t.text :checkpoint, **long_text
+      t.bigint :requested_by_id
+      t.bigint :answered_by_id
+      t.datetime :answered_at
+      t.datetime :expires_at
+      t.bigint :user_id
+      t.bigint :account_id
+      t.timestamps
+      t.index [ :subject_type, :subject_id ]
+      t.index :pause_key
+      t.index [ :status, :expires_at ]
+      t.index :user_id
+      t.index :account_id
+    end
+
+    agents = "#{prefix}agents"
+    reversible do |direction|
+      direction.up do
+        unless column_exists?(agents, :approval_required_tools)
+          add_column agents, :approval_required_tools, json_type, **json_default([])
+        end
+      end
+      direction.down do
+        remove_column agents, :approval_required_tools if column_exists?(agents, :approval_required_tools)
+      end
+    end
+  end
+
+  private
+
+  def json_type
+    @json_type ||= postgres? ? :jsonb : :json
+  end
+
+  # MySQL rejects a default on a JSON column outright, so the column is
+  # created without one there.
+  def json_default(value, null: nil)
+    return {} unless postgres?
+
+    null.nil? ? { default: value } : { default: value, null: null }
+  end
+
+  # MySQL's TEXT holds 64 KB, less than the encrypted checkpoint of a long
+  # conversation. Other adapters reject the option.
+  def long_text
+    mysql? ? { size: :long } : {}
+  end
+
+  def postgres?
+    connection.adapter_name.to_s.downcase.include?("postgres")
+  end
+
+  def mysql?
+    connection.adapter_name.to_s.downcase.match?(/mysql|trilogy/)
+  end
+end

data/lib/generators/action_agent/templates/migrations/017_create_active_agent_recording_events.rb.erb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+# Recording events: what a browser recorded during a session (rrweb DOM
+# events, console lines, markers, the agent's own browser actions, and human
+# input during a takeover), stored in batches. Each row holds one kind of
+# event from one batch, its payload gzip JSON either inline or attached
+# through Active Storage.
+#
+# Session recordings gain the conversation they belong to, where they came
+# from, the digest and expiry of the token a browser posts events with, and
+# the counters the per-recording caps are checked against.
+#
+# Table names follow ActionAgent.table_name_prefix, the same way as
+# create_active_agent_dashboard_tables.
+class CreateActiveAgentRecordingEvents < ActiveRecord::Migration<%= migration_version %>
+  def change
+    prefix = ActionAgent.table_name_prefix
+
+    create_table "#{prefix}recording_events" do |t|
+      t.bigint :session_recording_id, null: false
+      t.string :kind, null: false
+      # The batch's events span this range of server time, once the batch's
+      # clock offset is applied.
+      t.datetime :occurred_from, null: false
+      t.datetime :occurred_to, null: false
+      # Where this row's first event sat in its batch: orders the rows of one
+      # batch that share a start time.
+      t.integer :batch_index, default: 0, null: false
+      # Server receive time minus the client's send time, in milliseconds.
+      t.bigint :clock_offset_ms, default: 0, null: false
+      t.integer :event_count, default: 0, null: false
+      # The payload's size as JSON, before compression.
+      t.integer :byte_size, default: 0, null: false
+      # The limit makes MySQL create a column larger than a 64 KB BLOB.
+      t.binary :payload, limit: 16.megabytes
+      t.bigint :user_id
+      t.bigint :account_id
+      t.timestamps
+      t.index [ :session_recording_id, :occurred_from, :batch_index ]
+      t.index :user_id
+      t.index :account_id
+    end
+
+    change_table "#{prefix}session_recordings" do |t|
+      t.bigint :agent_context_id
+      # "agent" or "dashboard"; null on recordings made before this column.
+      t.string :source
+      t.string :ingest_token_digest
+      t.datetime :ingest_token_expires_at
+      t.integer :event_count, default: 0, null: false
+      t.bigint :event_bytes, default: 0, null: false
+      t.integer :dropped_event_count, default: 0, null: false
+      t.index :agent_context_id
+      t.index :ingest_token_digest, unique: true
+    end
+  end
+end

data/lib/generators/action_agent/templates/migrations/018_add_browser_to_active_agent_sandbox_sessions.rb.erb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+# Browser sessions: a sandbox can run one browser, driven over MCP by the
+# agents run against it. Each sandbox session records the browser's mode and
+# status, where its MCP endpoint answers and the bearer token it expects
+# (encrypted, like runtime_mcp_token), where a person can watch it, and when
+# it started, which is what its minutes are counted from.
+#
+# Table names follow ActionAgent.table_name_prefix, the same way as
+# create_active_agent_dashboard_tables.
+class AddBrowserToActiveAgentSandboxSessions < ActiveRecord::Migration<%= migration_version %>
+  def change
+    change_table "#{ActionAgent.table_name_prefix}sandbox_sessions" do |t|
+      # "headless" or "headed".
+      t.string :browser_mode
+      # "starting", "running", "stopped" or "failed"; null before a browser
+      # was ever started.
+      t.string :browser_status
+      t.string :browser_mcp_url
+      t.string :browser_live_url
+      t.text :browser_token
+      t.datetime :browser_started_at
+    end
+  end
+end

data/lib/generators/action_agent/templates/migrations/019_create_active_agent_projects.rb.erb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+# Projects: a repository the dashboard boots in a checkout sandbox, the
+# secrets that boot needs, and the agent and evaluation the project tests the
+# booted app with. A sandbox session records the project it was booted for.
+#
+# Table names follow ActionAgent.table_name_prefix, and JSON columns are
+# jsonb on PostgreSQL and json elsewhere, the same way as
+# create_active_agent_dashboard_tables.
+class CreateActiveAgentProjects < ActiveRecord::Migration<%= migration_version %>
+  def change
+    prefix = ActionAgent.table_name_prefix
+
+    create_table "#{prefix}projects" do |t|
+      t.string :name, null: false
+      # owner/name on GitHub, and the ref a boot checks out (the repository's
+      # default branch when blank).
+      t.string :repository, null: false
+      t.string :default_ref
+      t.string :start_url, null: false, default: "/"
+      t.string :status, null: false, default: "draft"
+      # detected: the repository does not bundle the engine; bootstrapped: a
+      # sandbox installed it; installed: the repository bundles it already.
+      t.string :install_state, null: false, default: "detected"
+      t.bigint :current_sandbox_session_id
+      t.bigint :target_agent_id
+      t.bigint :evaluation_id
+      t.column :settings, json_type, **json_default({})
+      t.bigint :account_id
+      t.bigint :user_id
+      t.timestamps
+      t.index :account_id
+      t.index :user_id
+      t.index :current_sandbox_session_id
+      t.index :target_agent_id
+    end
+
+    create_table "#{prefix}project_secrets" do |t|
+      t.bigint :project_id, null: false
+      t.string :name, null: false
+      # Encrypted at rest (text: ciphertext is longer than the value). Empty
+      # for a secret that uses the organization's provider key instead.
+      t.text :value
+      t.string :source, null: false, default: "entered"
+      t.string :provider
+      t.datetime :consented_at
+      t.bigint :set_by_id
+      t.bigint :account_id
+      t.bigint :user_id
+      t.timestamps
+      t.index [ :project_id, :name ], unique: true
+      t.index :account_id
+      t.index :user_id
+    end
+
+    change_table "#{prefix}sandbox_sessions" do |t|
+      t.bigint :project_id
+      t.index :project_id
+    end
+  end
+
+  private
+
+  def json_type
+    @json_type ||= postgres? ? :jsonb : :json
+  end
+
+  # MySQL rejects a default on a JSON column outright, so the column is
+  # created without one there.
+  def json_default(value, null: nil)
+    return {} unless postgres?
+
+    null.nil? ? { default: value } : { default: value, null: null }
+  end
+
+  def postgres?
+    connection.adapter_name.to_s.downcase.include?("postgres")
+  end
+end

data/lib/generators/action_agent/templates/migrations/020_add_github_app_installations.rb.erb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+# GitHub App installations an owner linked (Settings -> Integrations), the
+# repositories they chose on each, and the installation a checkout sandbox
+# clones through.
+#
+# Table names follow ActionAgent.table_name_prefix, and JSON columns are
+# jsonb on PostgreSQL and json elsewhere, the same way as
+# create_active_agent_dashboard_tables.
+class AddGithubAppInstallations < ActiveRecord::Migration<%= migration_version %>
+  def change
+    prefix = ActionAgent.table_name_prefix
+
+    create_table "#{prefix}github_installations" do |t|
+      # GitHub's installation id. Unique across every owner: one installation
+      # is linked to one owner at most.
+      t.bigint :installation_id, null: false
+      # The GitHub user or organization the App is installed on.
+      t.bigint :github_account_id, null: false
+      t.string :github_account_login, null: false
+      t.string :github_account_type, null: false
+      # "all" or "selected", as the installation was configured on GitHub.
+      t.string :repository_selection
+      # The permissions GitHub granted the installation.
+      t.column :permissions, json_type, **json_default({})
+      # The repositories the owner made available, shaped like
+      # github_connections.repositories.
+      t.column :repositories, json_type, **json_default([])
+      t.datetime :suspended_at
+      t.datetime :removed_at
+      t.bigint :user_id
+      t.bigint :account_id
+      t.timestamps
+      t.index :installation_id, unique: true, name: "index_#{prefix}github_installations_on_installation"
+      t.index :account_id, name: "index_#{prefix}github_installations_on_account"
+      t.index :user_id, name: "index_#{prefix}github_installations_on_user"
+    end
+
+    change_table "#{prefix}sandbox_sessions" do |t|
+      t.bigint :github_installation_id
+      t.index :github_installation_id, name: "index_#{prefix}sandbox_sessions_on_github_installation"
+    end
+  end
+
+  private
+
+  def json_type
+    @json_type ||= postgres? ? :jsonb : :json
+  end
+
+  # MySQL rejects a default on a JSON column outright, so the column is
+  # created without one there.
+  def json_default(value, null: nil)
+    return {} unless postgres?
+
+    null.nil? ? { default: value } : { default: value, null: null }
+  end
+
+  def postgres?
+    connection.adapter_name.to_s.downcase.include?("postgres")
+  end
+end

data/lib/generators/action_agent/templates/migrations/021_create_active_agent_explorations.rb.erb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+# Explorations: a walk through a project's running app, by the engine's
+# explorer agent or by an outside agent, and the candidate scenarios it
+# proposed for review. Accepted candidates are merged into the project's
+# evaluation; the rest stay here with their verdicts and provenance.
+#
+# Table names follow ActionAgent.table_name_prefix, and JSON columns are
+# jsonb on PostgreSQL and json elsewhere, the same way as
+# create_active_agent_dashboard_tables.
+class CreateActiveAgentExplorations < ActiveRecord::Migration<%= migration_version %>
+  def change
+    prefix = ActionAgent.table_name_prefix
+
+    create_table "#{prefix}explorations" do |t|
+      # At least one is set: a project's explorations merge into the
+      # project's evaluation, and one without a project into its own.
+      t.bigint :project_id
+      t.bigint :evaluation_id
+      t.bigint :agent_run_id
+      t.bigint :sandbox_session_id
+      t.bigint :session_recording_id
+      # explorer: the engine's explorer agent; external: candidates an
+      # outside agent submitted.
+      t.string :source, null: false, default: "external"
+      t.string :status, null: false, default: "pending"
+      t.string :start_url
+      t.string :stop_reason
+      t.text :error_message
+      t.datetime :started_at
+      t.datetime :finished_at
+      # { minutes, steps, cost }, the limits and what was used of them.
+      t.column :budget, json_type, **json_default({})
+      t.column :usage, json_type, **json_default({})
+      t.column :candidates, json_type, **json_default([])
+      t.bigint :account_id
+      t.bigint :user_id
+      t.timestamps
+      t.index :project_id
+      t.index :evaluation_id
+      t.index :account_id
+      t.index :user_id
+    end
+  end
+
+  private
+
+  def json_type
+    @json_type ||= postgres? ? :jsonb : :json
+  end
+
+  # MySQL rejects a default on a JSON column outright, so the column is
+  # created without one there.
+  def json_default(value, null: nil)
+    return {} unless postgres?
+
+    null.nil? ? { default: value } : { default: value, null: null }
+  end
+
+  def postgres?
+    connection.adapter_name.to_s.downcase.include?("postgres")
+  end
+end