actionagent 1.3.0 → 1.5.2

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

@@ -28,7 +28,7 @@ module ActionAgent
       def index
         # Scoped to the caller's own agents: this listed (and counted) every
         # run in the database regardless of who owned it.
-        scope = AgentRun.includes(:agent).where(agent: owner_agents).recent
+        scope = AgentRun.includes(:agent).with_attachments.where(agent: owner_agents).recent
 
         scope = scope.where(agent_id: params[:agent_id]) if params[:agent_id].present?
         scope = scope.where(status: params[:status]) if params[:status].present?
@@ -125,6 +125,8 @@ module ActionAgent
           total_tokens: run.total_tokens,
           error_message: run.error_message,
           trace_id: run.trace_id,
+          attachments: run.attachment_manifest,
+          context_id: run.context_id,
           logs: run.logs,
           started_at: run.started_at,
           completed_at: run.completed_at,

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

@@ -16,12 +16,23 @@ module ActionAgent
         "tokens" => "Most tokens"
       }.freeze
       DEFAULT_LIST_SORT = "recent"
-
-      before_action :set_agent, only: [ :show, :update, :destroy, :versions, :runs, :execute, :test, :restore, :duplicate, :export, :analytics ]
+      # Conversations returned to the runner's picker when no limit is asked for.
+      CONVERSATIONS_LIMIT = 50
+      # Keywords Agent#execute takes in its own right, which per-run overrides
+      # must never supply (see #execution_params).
+      RESERVED_EXECUTION_KEYS = [ :attachments, :action ].freeze
+
+      before_action :set_agent, only: [
+        :show, :update, :destroy, :versions, :runs, :execute, :test, :restore, :duplicate, :export, :analytics,
+        :conversations, :create_conversation
+      ]
       before_action :require_execution_enabled!, only: [ :execute, :test ]
       before_action :require_owner!, only: [ :execute, :test ]
-      before_action :require_executable_agent!, only: [ :execute, :test ]
+      before_action :require_executable_agent!, only: [ :execute, :test, :update, :restore, :create_conversation ]
       before_action :enforce_execution_quota!, only: [ :execute, :test ]
+      before_action :require_prompt!, only: [ :execute, :test ]
+
+      rescue_from AgentRun::AttachmentsUnavailable, with: :attachments_unavailable
 
       # GET /api/agents
       def index
@@ -55,7 +66,7 @@ module ActionAgent
             providers: Agent::PROVIDERS,
             preset_types: Agent::PRESET_TYPES,
             instruction_sets: Agent::INSTRUCTION_SETS,
-            available_tools: Agent::AVAILABLE_TOOLS
+            available_tools: Agent.available_tools
           }
         }
       end
@@ -65,7 +76,7 @@ module ActionAgent
         render json: {
           agent: agent_json(@agent, include_details: true),
           versions: @agent.agent_versions.recent.limit(10).map { |v| version_json(v) },
-          recent_runs: @agent.agent_runs.recent.limit(5).map(&:summary)
+          recent_runs: @agent.agent_runs.with_attachments.recent.limit(5).map(&:summary)
         }
       end
 
@@ -134,7 +145,7 @@ module ActionAgent
         # One digest->version map for the page; labels each run's instructions
         # with the agent version that introduced them where one matches.
         digest_versions = @agent.instructions_digest_versions
-        runs_by_id = AgentRun.where(id: executions[:rows].select { |r| r.source == "dashboard" }.map(&:id))
+        runs_by_id = AgentRun.with_attachments.where(id: executions[:rows].select { |r| r.source == "dashboard" }.map(&:id))
           .index_by(&:id)
 
         render json: {
@@ -150,11 +161,16 @@ module ActionAgent
       end
 
       # POST /api/agents/:id/execute
+      #
+      # JSON as before, or multipart from the runner's composer: the new
+      # user message, its files (attachments[]) and the conversation to
+      # continue (params[context_id], or a top-level context_id).
       def execute
         run = @agent.execute(
-          params[:prompt],
+          execution_prompt,
           action: params[:action_name],
-          **params.fetch(:params, {}).to_unsafe_h.symbolize_keys
+          attachments: uploaded_attachments,
+          **execution_params
         )
         record_execution_usage
 
@@ -164,15 +180,54 @@ module ActionAgent
       # POST /api/agents/:id/test
       def test
         run = @agent.test_execute(
-          params[:prompt],
+          execution_prompt,
           action: params[:action_name],
-          **params.fetch(:params, {}).to_unsafe_h.symbolize_keys
+          attachments: uploaded_attachments,
+          **execution_params
         )
         record_execution_usage
 
         render json: { run: run.summary, output: run.output }
       end
 
+      # GET /api/agents/:id/conversations
+      #
+      # The agent's persisted contexts, newest first — the runner's
+      # conversation picker, narrowed to one action when asked.
+      def conversations
+        limit = params.fetch(:limit, CONVERSATIONS_LIMIT).to_i.clamp(1, 200)
+        contexts = agent_contexts.order(created_at: :desc)
+        contexts = contexts.for_action(params[:action_name]) if params[:action_name].present?
+        # The picker is refetched on every seeded or deleted message, and the
+        # list grows a row per New conversation, so it is bounded like every
+        # other collection this API serves.
+        contexts = contexts.limit(limit).to_a
+        counts = AgentMessage.where(agent_context_id: contexts.map(&:id)).group(:agent_context_id).count
+
+        render json: {
+          conversations: contexts.map { |context| conversation_json(context, counts[context.id] || 0) }
+        }
+      end
+
+      # POST /api/agents/:id/conversations
+      #
+      # Starts an empty context for an action, so the runner's very first
+      # message already lands in a pinned conversation rather than in the
+      # agent's default stream.
+      def create_conversation
+        action = params[:action_name].presence || Agent::DEFAULT_ACTION
+        action = Agent::DEFAULT_ACTION unless @agent.available_actions.include?(action)
+
+        context = AgentContext.create!(
+          contextable: @agent,
+          agent_name: @agent.telemetry_agent_class,
+          action_name: action,
+          instructions: @agent.composed_instructions_for(action)
+        )
+
+        render json: { conversation: conversation_json(context, 0) }, status: :created
+      end
+
       # POST /api/agents/:id/duplicate
       def duplicate
         new_agent = @agent.dup
@@ -326,6 +381,58 @@ module ActionAgent
         }, status: :unprocessable_entity
       end
 
+      # A message may be empty only when files carry the request.
+      def require_prompt!
+        return if params[:prompt].present? || uploaded_attachments.any?
+
+        render json: { error: "Prompt can't be blank unless files are attached" }, status: :unprocessable_entity
+      end
+
+      def execution_prompt
+        params[:prompt].presence || "(see attached files)"
+      end
+
+      # Multipart files only: a JSON body can't carry one, and an empty file
+      # input arrives as a blank string.
+      def uploaded_attachments
+        @uploaded_attachments ||= Array(params[:attachments]).select { |file| file.respond_to?(:original_filename) }
+      end
+
+      # Per-run overrides (provider/model overrides, the pinned context)
+      # for input_params. context_id is stored as an integer so the JSON
+      # column reads the same whether a form or a JSON body delivered it;
+      # anything that isn't one is dropped rather than pinned to nothing.
+      def execution_params
+        extra = params.fetch(:params, {}).to_unsafe_h.symbolize_keys
+        # These reach Agent#execute as keywords, and a keyword splat wins over
+        # the arguments before it: left in, params[params][attachments] would
+        # replace the uploaded files with anything the caller names, and
+        # params[params][action] the action. They are the controller's to set.
+        extra.except!(*RESERVED_EXECUTION_KEYS)
+        context_id = Integer(extra.delete(:context_id).presence || params[:context_id].presence || 0, exception: false)
+        extra[:context_id] = context_id if context_id&.positive?
+        extra
+      end
+
+      def attachments_unavailable(exception)
+        render json: { error: exception.message }, status: :unprocessable_entity
+      end
+
+      def agent_contexts
+        AgentContext.where(contextable: @agent)
+      end
+
+      def conversation_json(context, message_count)
+        {
+          id: context.id,
+          action_name: context.action_name,
+          agent_name: context.agent_name,
+          message_count: message_count,
+          last_activity_at: context.updated_at.iso8601,
+          created_at: context.created_at.iso8601
+        }
+      end
+
       def list_sort(requested)
         LIST_SORTS.key?(requested.to_s) ? requested.to_s : DEFAULT_LIST_SORT
       end

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

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module ActionAgent
+  module Api
+    class DashboardAssistantController < BaseController
+      protect_from_forgery with: :exception
+
+      before_action :require_assistant_enabled!
+      before_action :require_owner!
+      before_action :require_execution_enabled!, only: :create
+      before_action :enforce_execution_quota!, only: :create
+
+      rescue_from DashboardAssistantService::InvalidInput, with: :invalid_input
+      rescue_from DashboardAssistantService::ProcessingConsentRequired, with: :processing_consent_required
+      rescue_from DashboardAssistantService::SetupRequired, with: :setup_required
+      # Rails 8.2 verifies forgery protection from the browser's Sec-Fetch-Site
+      # header, renamed the failure to InvalidCrossOriginRequest, and deprecated
+      # the old name. Rescue whichever names the running Rails defines, so a
+      # rejected request answers with the dashboard's JSON either way.
+      # const_defined? does not fire the deprecation the bare constant would.
+      rescue_from ActionController::InvalidCrossOriginRequest, with: :invalid_authenticity_token
+      if ActionController.const_defined?(:InvalidAuthenticityToken, false)
+        rescue_from ActionController::InvalidAuthenticityToken, with: :invalid_authenticity_token
+      end
+
+      def show
+        render json: DashboardAssistantService.new(owner: current_owner).configuration
+      end
+
+      def create
+        input = params.to_unsafe_h.symbolize_keys.slice(:message, :history, :provider, :model, :allow_provider_processing)
+        assistant = DashboardAssistantService.new(owner: current_owner, **input)
+        assistant.validate!
+        record_execution_usage
+        render json: assistant.call
+      rescue StandardError => exception
+        raise if exception.is_a?(DashboardAssistantService::InvalidInput) ||
+          exception.is_a?(DashboardAssistantService::ProcessingConsentRequired) ||
+          exception.is_a?(DashboardAssistantService::SetupRequired) ||
+          exception.is_a?(ActiveRecord::Encryption::Errors::Configuration)
+
+        # Provider exceptions can contain credentials or raw request bodies.
+        Rails.logger.warn("[DashboardAssistant] Generation failed (#{exception.class.name})")
+        render json: { error: "The assistant could not complete this request. Retry, or ask the dashboard administrator to check the server logs.", code: "generation_failed" }, status: :bad_gateway
+      end
+
+      private
+
+      # The assistant ships as a development and CI tool (see
+      # ActionAgent.assistant_enabled). Where it is off, it is not a view a
+      # caller can reach by knowing the route: the dashboard omits it, and
+      # both endpoints refuse.
+      def require_assistant_enabled!
+        return if ActionAgent.assistant_enabled?
+
+        render json: {
+          error: "The dashboard assistant is available in development and test. " \
+            "Set ActionAgent.assistant_enabled = true to enable it in this environment.",
+          code: "assistant_disabled"
+        }, status: :forbidden
+      end
+
+      def invalid_input(exception)
+        render json: { error: exception.message, code: "invalid_input" }, status: :unprocessable_entity
+      end
+
+      def processing_consent_required(exception)
+        render json: { error: exception.message, code: "processing_consent_required" }, status: :unprocessable_entity
+      end
+
+      def setup_required(exception)
+        render json: {
+          error: exception.message, code: "setup_required", setup_required: true,
+          action: { type: "open_settings", path: "/settings", label: "Configure provider" }
+        }, status: :service_unavailable
+      end
+
+      def invalid_authenticity_token
+        render json: { error: "Refresh the dashboard before sending another message", code: "invalid_csrf_token" }, status: :unprocessable_entity
+      end
+    end
+  end
+end

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

@@ -10,6 +10,10 @@ module ActionAgent
     # than sampling recorded generations, and can be narrowed to a group, to
     # specific scenarios, or to specific models.
     class EvaluationsController < BaseController
+      rescue_from ActiveAgent::Evals::ScenarioParser::ParseError do |error|
+        render json: { errors: [ error.message ] }, status: :unprocessable_entity
+      end
+
       before_action :require_owner!
       # A scenario suite replays its prompts through the provider, so creating
       # one that runs, or running one, executes the agent and is gated the way
@@ -237,11 +241,15 @@ module ActionAgent
         end
       end
 
-      # The refusal AgentsController gives an observed agent: it was
-      # discovered from telemetry and has nothing to execute.
+      # Observed agents cannot use the engine's execution service. A persisted
+      # evaluation with an explicit host adapter runs in that source instead.
       def require_executable_scenario_agent!
         agent = action_name == "create" ? requested_agent : current_evaluation.agent
         return unless agent.observed?
+        if action_name == "run"
+          adapter = ActionAgent.scenario_evaluation_adapter_resolver&.call(current_evaluation)
+          return if adapter.respond_to?(:call)
+        end
 
         render json: {
           error: "Observed agents are read-only — duplicate this agent to create an executable copy"
@@ -271,22 +279,29 @@ module ActionAgent
         }.compact_blank
       end
 
-      # Scenarios from the request: a pasted text block, a list of objects, or
-      # nothing (a generation-sampling evaluation).
+      # Scenarios from text, a YAML/JSON suite, or a list of objects. Production
+      # questions are selected at import time, only on explicit opt-in; the
+      # persisted scenario records do not store an environment flag.
       def scenario_attributes
         @scenario_attributes ||= begin
           source = params[:evaluation].presence || params
           text = source[:scenarios_text].to_s
           list = source[:scenarios]
+          include_production_only = ActiveModel::Type::Boolean.new.cast(source[:include_production_only]) == true
 
-          if list.present?
+          imported = if list.present?
             list = list.to_unsafe_h.values if list.is_a?(ActionController::Parameters)
-            ActiveAgent::Evals::ScenarioParser.parse(Array(list).map { |entry| entry.respond_to?(:to_unsafe_h) ? entry.to_unsafe_h : entry }.to_json)
+            serialized = Array(list).map { |entry| entry.respond_to?(:to_unsafe_h) ? entry.to_unsafe_h : entry }.to_json
+            ActiveAgent::Evals::ScenarioParser.parse(serialized, include_production_only: include_production_only)
           elsif text.present?
-            ActiveAgent::Evals::ScenarioParser.parse(text)
+            ActiveAgent::Evals::ScenarioParser.parse(text, include_production_only: include_production_only)
           else
             []
           end
+          if (list.present? || text.present?) && imported.empty?
+            raise ActiveAgent::Evals::ScenarioParser::ParseError, "No scenarios matched the import. Check the catalog or include_production_only selection."
+          end
+          imported
         end
       end
 

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

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module ActionAgent
+  module Api
+    # Edits to a conversation context from the agent runner: seed a user or
+    # assistant turn without running the agent, fix a turn's text, or drop
+    # one — so the next run sees exactly the history the tester intends.
+    #
+    # Only user and assistant turns are editable. Tool and system rows are
+    # written by execution and read back as call/result pairs; half a pair
+    # is worse than an uneditable one.
+    class InteractionMessagesController < BaseController
+      EDITABLE_ROLES = %w[user assistant].freeze
+
+      # Marks turns typed into the context by hand, as opposed to the
+      # provenance SolidAgent stamps on turns a run produced.
+      MANUAL_PROVENANCE = { "source" => "dashboard", "manual" => true }.freeze
+
+      rescue_from Agent::ObservedAgentError, with: :observed_agent_read_only
+
+      before_action :require_owner!
+      before_action :set_context
+      before_action :require_executable_agent!, only: [ :create, :update, :destroy ]
+      before_action :set_message, only: [ :update, :destroy ]
+
+      # POST /api/interactions/:interaction_id/messages
+      def create
+        role = params[:role].to_s
+        unless EDITABLE_ROLES.include?(role)
+          return render json: { error: "role must be user or assistant" }, status: :unprocessable_entity
+        end
+
+        content = params[:content].to_s
+        return render json: { error: "content can't be blank" }, status: :unprocessable_entity if content.blank?
+
+        message = @context.messages.create!(
+          role: role,
+          content: content,
+          content_checksum: Digest::MD5.hexdigest(content),
+          provenance: MANUAL_PROVENANCE
+        )
+        @context.touch
+
+        render json: { message: AgentMessageSerializer.call(message) }, status: :created
+      end
+
+      # PATCH /api/interactions/:interaction_id/messages/:id
+      def update
+        content = params[:content].to_s
+        return render json: { error: "content can't be blank" }, status: :unprocessable_entity if content.blank?
+
+        @message.update!(content: content, content_checksum: Digest::MD5.hexdigest(content))
+        @context.touch
+
+        render json: { message: AgentMessageSerializer.call(@message) }
+      end
+
+      # DELETE /api/interactions/:interaction_id/messages/:id
+      def destroy
+        @message.destroy!
+        @context.touch
+
+        head :no_content
+      end
+
+      private
+
+      def set_context
+        @context = AgentContext.for_agents(owner_agents).find(params[:interaction_id])
+      end
+
+      # Seeding, fixing or dropping a turn writes the agent's own history, so
+      # it answers to the same read-only policy execution does (#414): an
+      # observed agent is a mirror of someone else's telemetry, and a turn
+      # typed in here would be a fabrication attributed to it. Asked of the
+      # agent rather than re-tested here, so `observed` has one definition and
+      # one message. Reads are left open — every action this controller has is
+      # a write; the conversation itself is still listed and shown.
+      def require_executable_agent!
+        agent = @context.contextable
+        agent.ensure_executable! if agent.respond_to?(:ensure_executable!)
+      end
+
+      def observed_agent_read_only(exception)
+        render json: { error: exception.message }, status: :unprocessable_entity
+      end
+
+      # Looked up through the context, so a message id from another
+      # conversation is a 404 rather than a cross-conversation edit.
+      def set_message
+        @message = @context.messages.find(params[:id])
+        return if EDITABLE_ROLES.include?(@message.role)
+
+        render json: { error: "Only user and assistant messages can be edited" }, status: :unprocessable_entity
+      end
+    end
+  end
+end

data/app/controllers/action_agent/dashboard_controller.rb

@@ -41,8 +41,9 @@ module ActionAgent
         providers: Agent::PROVIDERS,
         presetTypes: Agent::PRESET_TYPES,
         instructionSets: Agent::INSTRUCTION_SETS,
-        availableTools: Agent::AVAILABLE_TOOLS,
+        availableTools: Agent.available_tools,
         executionEnabled: ActionAgent.execution_enabled?,
+        assistantEnabled: ActionAgent.assistant_enabled?,
         multiTenant: ActionAgent.multi_tenant?,
         upgradeUrl: ActionAgent.upgrade_url,
         signOutPath: ActionAgent.sign_out_path

data/app/models/action_agent/agent.rb

@@ -2,6 +2,8 @@
 
 module ActionAgent
   class Agent < ApplicationRecord
+    class ObservedAgentError < StandardError; end
+
     include Ownable
     owned_by :user, :account
 
@@ -39,6 +41,7 @@ module ActionAgent
 
     # Callbacks
     before_validation :generate_slug, on: :create
+    before_validation :apply_conventional_schema_tools, on: :create
     after_create :create_initial_version
     after_update :create_version_on_config_change, if: :configuration_changed?
 
@@ -70,17 +73,62 @@ module ActionAgent
       github ruby rails aws gcp python typescript docker kubernetes
     ].freeze
 
-    # Available tools/MCPs
+    # Built-in tools/MCPs. Host-declared schema tools are offered alongside
+    # these — see .available_tools, which is what the editor and the APIs
+    # serialize. This constant stays the built-in set so existing references
+    # keep their meaning.
     AVAILABLE_TOOLS = %w[
-      terminal playwright filesystem code database slack fetch search edit translate memory agents
+      terminal playwright filesystem code database slack fetch search edit translate memory agents ui
     ].freeze
 
+    # Every tool an agent may enable: the built-ins plus each tool generated by
+    # the host's declared ActiveAgent::SchemaTools classes (ActionAgent.schema_tools).
+    #
+    # Computed per call, never memoized: in development the host's tool classes
+    # are autoloaded and reloaded, so a cached list would either miss them at
+    # boot or go stale after a reload.
+    # @return [Array<String>]
+    def self.available_tools
+      AVAILABLE_TOOLS | ActionAgent.schema_tool_names
+    end
+
     # 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.
+    # Tools a schema tool class claims for this agent by naming convention:
+    # Reservation -> ReservationTools -> ReservationAgent.
+    #
+    # This is a DEFAULT SELECTION, never a restriction. Any agent may enable
+    # any tool in .available_tools; the convention only decides what a newly
+    # created ReservationAgent starts with.
+    # @return [Array<String>]
+    def conventional_schema_tools
+      # Compared on letters only. `telemetry_agent_class` is not reliable here:
+      # it runs `parameterize.camelize`, which turns an already-camelised
+      # "TicketAgent" into "Ticketagent" and matches nothing, while
+      # "Milestone Agent" happens to survive. Normalising both sides makes
+      # "TicketAgent", "Ticket Agent" and "ticket_agent" all match.
+      identifier = (agent_class_name.presence || name.to_s).gsub(/[^a-z]/i, "").downcase
+      return [] if identifier.blank?
+
+      ActionAgent.schema_tool_classes.select do |klass|
+        "#{klass.model.name}Agent".downcase == identifier
+      end.flat_map(&:tool_names).map(&:to_s)
+    end
+
+    # Seeds a new agent named after a model with that model's tools. Only on
+    # create, and only when none were chosen — a deliberate selection, empty
+    # included, is never overwritten, and the editor can deselect afterwards.
+    def apply_conventional_schema_tools
+      return if tools.present?
+
+      defaults = conventional_schema_tools
+      self.tools = defaults if defaults.any?
+    end
+
     def telemetry_agent_class
       base = agent_class_name.presence || name.parameterize(separator: "_").camelize
       base.end_with?("Agent") ? base : "#{base}Agent"
@@ -201,15 +249,14 @@ module ActionAgent
       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
-      )
+    # Execute a run with this agent. Files in +attachments+ (uploaded files,
+    # {io:, filename:, content_type:} hashes or blobs) are stored on the run
+    # before the job is enqueued, so a worker on another machine finds them
+    # attached. +params+ (provider/model overrides, the context_id of a
+    # conversation to continue) are kept on the run as input_params.
+    def execute(input_prompt, action: nil, attachments: [], **params)
+      ensure_executable!
+      run = create_run(input_prompt, action: action, attachments: attachments, params: params, status: :pending)
 
       # Queue the execution job
       AgentExecutionJob.perform_later(run.id)
@@ -218,14 +265,11 @@ module ActionAgent
     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
+    def test_execute(input_prompt, action: nil, attachments: [], **params)
+      ensure_executable!
+      run = create_run(
+        input_prompt, action: action, attachments: attachments, params: params,
+        status: :running, started_at: Time.current
       )
 
       begin
@@ -254,8 +298,52 @@ module ActionAgent
       run
     end
 
+    # An observed agent was reconstructed from telemetry, so it is read-only:
+    # editing it would rewrite a record of what ran. Executing it is a
+    # different question — it carries the instructions, model and MCP servers a
+    # run needs, and evaluating the agent that actually served production is
+    # the case operators ask for. So a run is allowed once the agent names a
+    # server the dashboard can reach, and refused when it would have nothing to
+    # call.
+    def ensure_executable!
+      return unless observed?
+      return if MCPToolDispatcher.new(self).any_reachable_server?
+
+      raise ObservedAgentError,
+            "This agent was observed from telemetry and is read-only: it names no reachable MCP server — duplicate it to create an executable copy"
+    end
+
     private
 
+    # Refuses files before creating anything: a run that exists but lost
+    # its attachments would execute against the wrong prompt.
+    def create_run(input_prompt, action:, attachments:, params:, **attributes)
+      files = Array.wrap(attachments).compact
+      raise AgentRun::AttachmentsUnavailable if files.any? && !AgentRun.attachments_available?
+
+      run = agent_runs.create!(
+        input_prompt: input_prompt,
+        action_name: normalized_action(action),
+        input_params: params,
+        trace_id: SecureRandom.uuid,
+        **attributes
+      )
+
+      if files.any?
+        begin
+          run.attachments.attach(*files)
+        rescue StandardError
+          # An attach that raises (an unwritable service, a value that is not
+          # a file) happens after the row exists, and the caller never reaches
+          # the enqueue: without this the run would sit pending forever.
+          run.destroy
+          raise
+        end
+      end
+
+      run
+    end
+
     def slug_unique_within_owner
       return if slug.blank?