actionagent 1.5.2 → 1.6.2

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

@@ -33,8 +33,8 @@ module ActionAgent
         scope = scope.where(agent_id: params[:agent_id]) if params[:agent_id].present?
         scope = scope.where(status: params[:status]) if params[:status].present?
 
-        page = (params[:page] || 1).to_i
-        per_page = (params[:per_page] || 20).to_i
+        page = integer_param(:page, default: 1)
+        per_page = integer_param(:per_page, default: 20)
         total = scope.count
         runs = scope.offset((page - 1) * per_page).limit(per_page)
 

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

@@ -19,12 +19,15 @@ module ActionAgent
       # 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
+      # must never supply (see #execution_params). `actor` is here for the
+      # same reason as the rest and one more: a keyword splat wins over the
+      # arguments before it, so a client sending params[params][actor] would
+      # otherwise name the caller its own run is authorized as.
+      RESERVED_EXECUTION_KEYS = [ :attachments, :action, :actor, :current_user ].freeze
 
       before_action :set_agent, only: [
         :show, :update, :destroy, :versions, :runs, :execute, :test, :restore, :duplicate, :export, :analytics,
-        :conversations, :create_conversation
+        :tool_roster, :conversations, :create_conversation
       ]
       before_action :require_execution_enabled!, only: [ :execute, :test ]
       before_action :require_owner!, only: [ :execute, :test ]
@@ -129,9 +132,9 @@ module ActionAgent
       # observed from telemetry have no AgentRun rows at all, so a runs-only
       # list showed them as empty while their scorecard reported real traffic.
       def runs
-        minutes = params[:minutes].presence&.then { |m| m.to_i.clamp(1, 60 * 24 * 90) }
-        page = (params[:page] || 1).to_i
-        per_page = (params[:per_page] || 20).to_i
+        minutes = integer_param(:minutes)&.clamp(1, 60 * 24 * 90)
+        page = integer_param(:page, default: 1)
+        per_page = integer_param(:per_page, default: 20)
 
         executions = AgentExecutions.new(
           agents: [ @agent ],
@@ -170,6 +173,7 @@ module ActionAgent
           execution_prompt,
           action: params[:action_name],
           attachments: uploaded_attachments,
+          actor: agent_actor,
           **execution_params
         )
         record_execution_usage
@@ -183,6 +187,7 @@ module ActionAgent
           execution_prompt,
           action: params[:action_name],
           attachments: uploaded_attachments,
+          actor: agent_actor,
           **execution_params
         )
         record_execution_usage
@@ -256,6 +261,19 @@ module ActionAgent
         }
       end
 
+      # GET /api/agents/:id/tool_roster
+      #
+      # What the Tools tab edits: the MCP services this agent can be given
+      # and the tools it can be offered, each with the calls, errors and
+      # latency recorded for it in the window.
+      def tool_roster
+        render json: AgentToolRoster.new(
+          agent: @agent,
+          traces: owned_traces,
+          hours: params.fetch(:hours, ToolDiscovery::DEFAULT_WINDOW_HOURS).to_i
+        ).as_json
+      end
+
       # GET /api/agents/:id/analytics
       #
       # Every execution of this agent, whoever ran it — the same merged model
@@ -264,7 +282,7 @@ module ActionAgent
       # with all-zero metrics beside a card and a runs list reporting real
       # traffic.
       def analytics
-        days = (params[:days] || 30).to_i
+        days = integer_param(:days, default: 30)
         start_date = days.days.ago.beginning_of_day
 
         runs = @agent.agent_runs.where("created_at >= ?", start_date)
@@ -478,17 +496,33 @@ module ActionAgent
       end
 
       def agent_params
-        params.require(:agent).permit(
+        permitted = params.require(:agent).permit(
           :name, :description, :provider, :model, :instructions,
           :preset_type, :agent_class_name, :status,
           appearance: {},
           action_prompts: [ :name, :prompt, :expose_as_tool ],
           instruction_sets: [],
           tools: [],
-          mcp_servers: [],
           model_config: {},
           response_format: {}
         )
+        permitted[:mcp_servers] = mcp_server_params if params[:agent].key?(:mcp_servers)
+        permitted
+      end
+
+      # An agent names its MCP servers either as bare strings or as hashes —
+      # the Tools tab writes { key, name, tools } so a service can be enabled
+      # with only some of what it serves. Both shapes are permitted, because
+      # every agent saved before the tab existed carries the first one and a
+      # round-trip through the editor must not rewrite it.
+      def mcp_server_params
+        Array(params[:agent][:mcp_servers]).map do |entry|
+          if entry.respond_to?(:permit)
+            entry.permit(:key, :name, :url, :command, :transport, tools: []).to_h
+          else
+            entry.to_s
+          end
+        end
       end
 
       def version_json(version, include_diff: false)
@@ -498,7 +532,10 @@ module ActionAgent
           change_summary: version.change_summary,
           created_by: version.created_by,
           created_at: version.created_at,
-          is_latest: version.latest?
+          is_latest: version.latest?,
+          release: version.release?,
+          release_digest: version.release_digest,
+          revision: version.revision
         }
 
         if include_diff && version.previous

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

@@ -5,7 +5,7 @@ module ActionAgent
     class AnalyticsController < BaseController
       # GET /api/analytics
       def index
-        days = (params[:days] || 30).to_i
+        days = integer_param(:days, default: 30)
         start_date = days.days.ago.beginning_of_day
 
         # Table names are interpolated rather than written literally: the

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

@@ -68,6 +68,23 @@ module ActionAgent
         ActionAgent.trace_model.for_account(current_account)
       end
 
+      # The caller an agent run executes on behalf of.
+      #
+      # The host's seam first (ActionAgent.agent_actor_resolver), then the
+      # signed-in user. Never the tenant: an account is who is billed, not
+      # who is allowed, and handing a Pundit policy an account would either
+      # raise or quietly authorize as the whole workspace.
+      def agent_actor
+        return @agent_actor if defined?(@agent_actor)
+
+        @agent_actor =
+          if (resolver = ActionAgent.agent_actor_resolver)
+            resolver.arity.zero? ? resolver.call : resolver.call(self)
+          else
+            current_user
+          end
+      end
+
       # The tenant, when the host app has one. current_owner already
       # resolves it in multi-tenant mode; single-tenant installs have none.
       def current_account
@@ -112,6 +129,26 @@ module ActionAgent
         render json: { error: "Agent execution is disabled on this dashboard" }, status: :forbidden
       end
 
+      # An integer query param. A value can arrive as a container
+      # (`minutes[]=1&minutes[]=2`, or `page[x]=1`), and neither Array nor
+      # ActionController::Parameters responds to `to_i`: reading them
+      # directly raised NoMethodError and turned a malformed query into a
+      # 500. A multi-valued param means its first value; anything else that
+      # is not a scalar falls back to the default.
+      def integer_param(name, default: nil)
+        raw = params[name]
+        raw = raw.first if raw.is_a?(Array)
+        return default if raw.blank? || !(raw.is_a?(String) || raw.is_a?(Numeric))
+
+        raw.to_s.to_i
+      end
+
+      # integer_param, then clamped into [min, max]. Non-numeric input becomes
+      # 0 and is then clamped up to `min`.
+      def clamped_param(name, default:, min:, max:)
+        integer_param(name, default: default).clamp(min, max)
+      end
+
       def not_found
         render json: { error: "Record not found" }, status: :not_found
       end

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

@@ -16,7 +16,7 @@ module ActionAgent
 
       # GET /api/interactions
       def index
-        limit = params.fetch(:limit, DEFAULT_LIMIT).to_i.clamp(1, 200)
+        limit = clamped_param(:limit, default: DEFAULT_LIMIT, min: 1, max: 200)
 
         contexts = interactions_scope
           .includes(:contextable)
@@ -140,8 +140,8 @@ module ActionAgent
       def window_minutes
         return @window_minutes if defined?(@window_minutes)
 
-        raw = params[:minutes].presence
-        @window_minutes = raw ? raw.to_i.clamp(1, MAX_WINDOW_MINUTES) : nil
+        raw = integer_param(:minutes)
+        @window_minutes = raw ? raw.clamp(1, MAX_WINDOW_MINUTES) : nil
       end
 
       def interactions_scope

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

@@ -7,7 +7,11 @@ module ActionAgent
     # themselves as Resource Agents backed by their ActiveRecord state:
     #
     # - tools/list & tools/call: each agent is a callable tool (run_<slug>)
-    #   that executes a synchronous generation run.
+    #   that executes a synchronous generation run, and each of the host's
+    #   schema tools (ActiveAgent::SchemaTools, the classes the dashboard
+    #   discovers) is callable directly — find_<records>, count_<records>,
+    #   get_<record> — as this key's caller, so a client reads the host's
+    #   records under the same scope an agent run would (#439).
     # - resources/list & resources/read: each agent is an agent://<slug>
     #   resource whose content is its live scorecard (config + stats + memory
     #   summary from the solid_agent datasets).
@@ -28,6 +32,10 @@ module ActionAgent
       JSONRPC_METHOD_NOT_FOUND = -32601
       JSONRPC_INVALID_PARAMS = -32602
       JSONRPC_SERVER_ERROR = -32000
+      # No JSON-RPC code means "forbidden", and the MCP spec leaves -32000..
+      # -32099 to the server. A refusal gets its own so a client can tell it
+      # from a run that merely failed.
+      JSONRPC_FORBIDDEN = -32003
 
       # POST /mcp
       def create
@@ -102,12 +110,46 @@ module ActionAgent
         ActionAgent.agents_for(@owner).where.not(status: :archived).order(:slug)
       end
 
+      # The caller an MCP-invoked run executes on behalf of.
+      #
+      # The key's owner is the identity that authenticated this request, so
+      # it is the default; a host issuing keys per end user overrides it
+      # with ActionAgent.agent_actor_resolver, which is handed this
+      # controller and can read the request however it likes.
+      #
+      # The agent's own callbacks decide what the actor may do — that is the
+      # point of carrying one. This only answers *who*.
+      def agent_actor
+        return @agent_actor if defined?(@agent_actor)
+
+        @agent_actor =
+          if (resolver = ActionAgent.agent_actor_resolver)
+            resolver.arity.zero? ? resolver.call : resolver.call(self)
+          else
+            @api_key.respond_to?(:user) && @api_key.user ? @api_key.user : @owner
+          end
+      end
+
+      # Whether the run ended because the agent refused this caller, rather
+      # than because something broke. Matched on the error class the
+      # framework raises (and the ones a host names with `denies_with`), not
+      # on the message.
+      def run_refused?(run)
+        klass = run.output_metadata.is_a?(Hash) ? run.output_metadata["error_class"] : nil
+        return false if klass.blank?
+
+        klass.to_s == "ActiveAgent::NotAuthorized" ||
+          ActiveAgent::Base.authorization_errors.any? { |error| error.name == klass.to_s }
+      end
+
       def initialize_result
         {
           protocolVersion: PROTOCOL_VERSION,
           capabilities: { tools: {}, resources: {} },
           serverInfo: { name: "activeagents", version: "1.0" },
-          instructions: "Each tool runs one of this account's agents. Each agent://<slug> resource returns the agent's live scorecard."
+          instructions: "Each run_<slug> tool runs one of this account's agents; every other tool reads the host " \
+                        "application's records directly, as the caller this key authenticates. Each agent://<slug> " \
+                        "resource returns the agent's live scorecard."
         }
       end
 
@@ -138,11 +180,32 @@ module ActionAgent
           agent_tools
         end
 
-        { tools: tools }
+        { tools: tools + schema_tools_list }
+      end
+
+      # The host's schema tools, offered as the same tool definitions an
+      # agent run receives — the parameter schema is the tool's own, so a
+      # client sees which columns it may filter on. Every generated tool of
+      # every discovered class is listed; the host chose what to declare, and
+      # ActionAgent.mcp_schema_tools switches the whole set off.
+      def schema_tools_list
+        return [] unless ActionAgent.mcp_schema_tools?
+
+        ActionAgent.schema_tool_classes.flat_map do |klass|
+          klass.tool_definitions.map do |definition|
+            {
+              name: definition[:name],
+              description: definition[:description],
+              inputSchema: definition[:parameters] || definition[:input_schema] || { type: "object", properties: {} }
+            }
+          end
+        end
       end
 
       def tools_call
         name = params.dig(:params, :name).to_s
+        return schema_tool_call(name) if ActionAgent.mcp_schema_tools? && ActionAgent.schema_tool_class_for(name)
+
         slug, action = name.delete_prefix("run_").split("__", 2)
         agent = key_agents.find_by(slug: slug)
         raise McpError.new("Unknown tool: #{name}", JSONRPC_INVALID_PARAMS) unless agent
@@ -160,10 +223,16 @@ module ActionAgent
           raise McpError.new(denial.is_a?(Hash) ? denial[:message] || denial["message"] : denial)
         end
 
-        run = agent.test_execute(message, action: action)
+        run = agent.test_execute(message, action: action, actor: agent_actor)
         ActionAgent.record_usage(@owner, :execution)
 
         if run.failed?
+          # A refusal is not a result. An agent that declined on this
+          # caller's behalf answers as a JSON-RPC error, so the client sees
+          # "not allowed" rather than an empty, confident answer — the
+          # failure mode a nil-actor scope produces on its own.
+          raise McpError.new(run.error_message.to_s, JSONRPC_FORBIDDEN) if run_refused?(run)
+
           { content: [ { type: "text", text: "Agent run failed: #{run.error_message}" } ], isError: true }
         else
           {
@@ -179,6 +248,48 @@ module ActionAgent
         end
       end
 
+      # Calls a schema tool directly, as this key's caller. No generation runs,
+      # so neither the execution switch nor the execution quota applies: this
+      # is a read of the host's records through the host's own scope.
+      #
+      # A boundary violation — an undeclared filter, an id the caller cannot
+      # see — comes back as a tool result with isError, the shape an agent
+      # run would hand its model, so a client can correct its call. A refusal
+      # raised by the host's scope (an authorization gem's error, or
+      # ActiveAgent::NotAuthorized) answers as a JSON-RPC error, as an
+      # agent's refusal does.
+      def schema_tool_call(name)
+        klass = ActionAgent.schema_tool_class_for(name)
+        result = call_schema_tool(klass, name)
+        response = { content: [ { type: "text", text: result.to_json } ], structuredContent: result }
+        response[:isError] = true if result.respond_to?(:key?) && (result.key?(:error) || result.key?("error"))
+        response
+      end
+
+      def call_schema_tool(klass, name)
+        klass.call(name, actor: agent_actor, **schema_tool_arguments)
+      rescue StandardError => e
+        raise McpError.new(e.message, JSONRPC_FORBIDDEN) if authorization_error?(e)
+
+        raise
+      end
+
+      # The framework's refusal (the default in Base.authorization_errors), or
+      # one of the errors a host named with `denies_with` — matched on the
+      # class, as run_refused? matches a run's.
+      def authorization_error?(error)
+        ActiveAgent::Base.authorization_errors.any? { |klass| error.is_a?(klass) }
+      end
+
+      # The call's arguments as keywords, minus any that name the caller:
+      # the actor is the key's identity, never something a client sends
+      # (AgentExecutionService::ACTOR_KEYWORDS, for the same reason).
+      def schema_tool_arguments
+        arguments = params.dig(:params, :arguments)
+        arguments = arguments.respond_to?(:to_unsafe_h) ? arguments.to_unsafe_h : arguments.to_h
+        arguments.to_h.symbolize_keys.except(*AgentExecutionService::ACTOR_KEYWORDS)
+      end
+
       def resources_list
         {
           resources: key_agents.map do |agent|

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

@@ -18,11 +18,16 @@ module ActionAgent
       # POST /api/sandboxes/compare
       # Run multiple providers in a single sandbox using parallel generation jobs
       def compare
-        providers = params[:providers] || %w[anthropic openai ollama]
+        providers = params[:providers].nil? ? %w[anthropic openai ollama] : params[:providers]
         task = params[:task]
         sandbox_id = params[:sandbox_id]
 
         return render json: { error: "Task required" }, status: :bad_request unless task.present?
+        # A bare string or a nested object is a malformed request, not a list
+        # of one provider: reading it as a list raised NoMethodError.
+        unless providers.is_a?(Array) && providers.all? { |name| name.is_a?(String) }
+          return render json: { error: "providers must be a list of provider names" }, status: :bad_request
+        end
         return render json: { error: "At least 2 providers required" }, status: :bad_request if providers.size < 2
 
         # Validate providers

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

@@ -13,6 +13,12 @@ module ActionAgent
 
       before_action :set_recording, only: [ :show, :actions, :snapshot, :export, :handoff ]
 
+      # Browser state that must never leave the server in a read response:
+      # the handoff state a recording carries is a copy of the visitor's
+      # cookies and web storage. Only #handoff returns it, to the owner, when
+      # they continue the session.
+      SENSITIVE_STATE_KEYS = %w[cookies session_storage local_storage].freeze
+
       # GET /api/session_recordings
       # List recordings with optional filters
       def index
@@ -36,8 +42,8 @@ module ActionAgent
         end
 
         # Pagination
-        page = (params[:page] || 1).to_i
-        per_page = [ (params[:per_page] || 20).to_i, 100 ].min
+        page = integer_param(:page, default: 1)
+        per_page = [ integer_param(:per_page, default: 20), 100 ].min
         offset = (page - 1) * per_page
 
         total = recordings.count
@@ -79,10 +85,10 @@ module ActionAgent
 
         # Support pagination for large recordings
         if params[:after_sequence].present?
-          actions = actions.where("sequence > ?", params[:after_sequence].to_i)
+          actions = actions.where("sequence > ?", integer_param(:after_sequence, default: 0))
         end
 
-        limit = [ params[:limit]&.to_i || 100, 500 ].min
+        limit = [ integer_param(:limit, default: 100), 500 ].min
         actions = actions.limit(limit)
 
         render json: {
@@ -332,7 +338,7 @@ module ActionAgent
           created_at: recording.created_at.iso8601,
           updated_at: recording.updated_at.iso8601,
           timeline: recording.timeline,
-          handoff_state: recording.metadata["handoff_state"],
+          handoff_state: safe_handoff_state(recording.metadata["handoff_state"]),
           agent: recording.agent_run&.agent&.slice(:id, :name),
           sandbox_session: recording.sandbox_session&.summary
         }
@@ -343,9 +349,20 @@ module ActionAgent
         action&.screenshot_url(expires_in: 1.hour)
       end
 
+      # Strips the browser state at the top level and inside handoff_state,
+      # which the model stores nested (a recording's metadata carries the
+      # handoff as one key), so a show response never ships a session cookie.
       def safe_metadata(metadata)
-        # Remove sensitive data from metadata
-        metadata.except("cookies", "session_storage", "local_storage")
+        safe = (metadata || {}).except(*SENSITIVE_STATE_KEYS)
+        return safe unless safe["handoff_state"].is_a?(Hash)
+
+        safe.merge("handoff_state" => safe_handoff_state(safe["handoff_state"]))
+      end
+
+      def safe_handoff_state(handoff_state)
+        return handoff_state unless handoff_state.is_a?(Hash)
+
+        handoff_state.except(*SENSITIVE_STATE_KEYS)
       end
 
       def generate_visitor_id

data/app/jobs/action_agent/agent_execution_job.rb

@@ -38,7 +38,10 @@ module ActionAgent
             status: :failed,
             completed_at: Time.current,
             error_message: e.message,
-            error_backtrace: e.backtrace&.first(10)&.join("\n")
+            error_backtrace: e.backtrace&.first(10)&.join("\n"),
+            # Same as the synchronous path: the class is what distinguishes
+            # a refusal from a crash.
+            output_metadata: run.output_metadata.to_h.merge("error_class" => e.class.name)
           )
           run.add_log("Execution failed: #{e.message}", level: :error)
         end

data/app/models/action_agent/agent.rb

@@ -81,6 +81,25 @@ module ActionAgent
       terminal playwright filesystem code database slack fetch search edit translate memory agents ui
     ].freeze
 
+    # One line per capability, for the roster rows that offer them. A name
+    # alone ("ui", "agents") doesn't say what enabling it gives the model,
+    # and the Tools tab is where that question gets asked.
+    TOOL_DESCRIPTIONS = {
+      "terminal" => "Runs a shell command in the workspace sandbox.",
+      "playwright" => "Drives a headless browser: navigate, click, read the page.",
+      "filesystem" => "Reads and writes files under an allow-listed set of directories.",
+      "code" => "Reads and edits files in the connected repository.",
+      "database" => "Runs read-only SQL against the app database.",
+      "slack" => "Reads channels and posts messages as the workspace bot.",
+      "fetch" => "Fetches a URL and converts the page to markdown for the model to read.",
+      "search" => "Web search through the workspace provider.",
+      "edit" => "Applies a structured edit to a document.",
+      "translate" => "Translates text through the translation agent.",
+      "memory" => "Reads and writes durable notes across runs of this agent.",
+      "agents" => "Delegates a task to another agent in this workspace.",
+      "ui" => "Renders a form or table back into the chat surface."
+    }.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).
     #
@@ -200,6 +219,46 @@ module ActionAgent
       agent_versions.order(version_number: :desc).first
     end
 
+    # The most recent version cut from the agent's code, if any.
+    # @return [AgentVersion, nil]
+    def latest_release
+      agent_versions.releases.order(version_number: :desc).first
+    end
+
+    # Cuts a version for a release of the agent's code, identified by the
+    # digest ActiveAgent::Release computes from what the model is given.
+    # Returns the existing version when the latest release already carries
+    # this digest — a redeploy of an unchanged agent is not a new version —
+    # so it is safe to call on every deploy.
+    #
+    # The version's snapshot is the dashboard configuration plus the release
+    # manifest under "release", so the Versions tab can diff two releases the
+    # same way it diffs two dashboard edits.
+    #
+    # @param digest [String] ActiveAgent::Release digest of the host class
+    # @param manifest [Hash, nil] the class's release manifest
+    # @param revision [String, nil] the deploy (git SHA, release label)
+    # @param released_by [String, nil]
+    # @return [AgentVersion]
+    def record_release!(digest:, manifest: nil, revision: nil, released_by: nil)
+      current = latest_release
+      if current && current.release_digest == digest
+        update_columns(release_digest: digest) if release_digest != digest
+        return current
+      end
+
+      version = agent_versions.create!(
+        version_number: (latest_version&.version_number || 0) + 1,
+        change_summary: release_summary(digest, revision, current&.configuration_snapshot&.dig("release"), manifest),
+        configuration_snapshot: configuration_snapshot.merge("release" => manifest || {}),
+        release_digest: digest,
+        revision: revision,
+        created_by: released_by || "release"
+      )
+      update_columns(release_digest: digest)
+      version
+    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.
@@ -254,9 +313,12 @@ module ActionAgent
     # 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)
+    def execute(input_prompt, action: nil, attachments: [], actor: nil, **params)
       ensure_executable!
-      run = create_run(input_prompt, action: action, attachments: attachments, params: params, status: :pending)
+      run = create_run(
+        input_prompt, action: action, attachments: attachments, params: params,
+        actor: actor, status: :pending
+      )
 
       # Queue the execution job
       AgentExecutionJob.perform_later(run.id)
@@ -265,12 +327,13 @@ module ActionAgent
     end
 
     # Quick test execution (synchronous)
-    def test_execute(input_prompt, action: nil, attachments: [], **params)
+    def test_execute(input_prompt, action: nil, attachments: [], actor: nil, **params)
       ensure_executable!
       run = create_run(
         input_prompt, action: action, attachments: attachments, params: params,
-        status: :running, started_at: Time.current
+        actor: actor, status: :running, started_at: Time.current
       )
+      run.actor = actor
 
       begin
         # Build and execute the agent
@@ -291,7 +354,11 @@ module ActionAgent
           status: :failed,
           completed_at: Time.current,
           error_message: e.message,
-          error_backtrace: e.backtrace&.first(10)&.join("\n")
+          error_backtrace: e.backtrace&.first(10)&.join("\n"),
+          # The class, not only the message: an agent that refused this
+          # caller and an agent that broke both fail the run, and only the
+          # class tells them apart without reading prose.
+          output_metadata: run.output_metadata.to_h.merge("error_class" => e.class.name)
         )
       end
 
@@ -317,14 +384,16 @@ module ActionAgent
 
     # 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)
+    def create_run(input_prompt, action:, attachments:, params:, actor: nil, **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,
+        # The caller is recorded beside the run's own parameters rather than
+        # among them: a client may send provider overrides, never an actor.
+        input_params: AgentRun.params_with_actor(params, actor),
         trace_id: SecureRandom.uuid,
         **attributes
       )
@@ -367,6 +436,18 @@ module ActionAgent
       end
     end
 
+    # "Release 1a2b3c4d5e6f · abc1234: templates, tools" — the digest, the
+    # deploy, and which parts of the manifest moved since the last release.
+    def release_summary(digest, revision, previous_manifest, manifest)
+      label = [ "Release #{digest}", revision.presence ].compact.join(" · ")
+      return "#{label}: first release" if previous_manifest.blank? || manifest.blank?
+
+      changed = (previous_manifest.keys | manifest.stringify_keys.keys).select do |key|
+        previous_manifest[key] != manifest.stringify_keys[key]
+      end
+      changed.any? ? "#{label}: #{changed.sort.join(', ')}" : label
+    end
+
     def create_initial_version
       agent_versions.create!(
         version_number: 1,