actionagent 1.5.2 → 1.6.0

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 ]
@@ -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
@@ -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)

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

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/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).
     #
@@ -254,9 +273,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 +287,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 +314,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 +344,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
       )

data/app/models/action_agent/agent_run.rb

@@ -20,6 +20,55 @@ module ActionAgent
     # --skip-active-storage has no has_many_attached to call.
     has_many_attached :attachments if defined?(ActiveStorage)
 
+    # The key the caller's identity is recorded under in +input_params+.
+    # Underscored so it cannot collide with a provider override, and
+    # stripped from anything a client sends (see Api::AgentsController).
+    ACTOR_PARAM = "_actor_gid"
+
+    # +input_params+ with the caller recorded alongside them.
+    #
+    # The actor is stored as a Global ID rather than as the record, so the
+    # worker that picks the run up — on another machine, minutes later —
+    # authorizes as the same person who asked for the run. A caller the host
+    # cannot address that way (a plain object, a service account) is simply
+    # not recorded: the run then executes unattributed, which a host scope
+    # reads as "no access", rather than executing as somebody else.
+    #
+    # @param params [Hash] the run's own parameters
+    # @param actor [Object, nil] the caller
+    # @return [Hash]
+    def self.params_with_actor(params, actor)
+      params = (params || {}).to_h.except(ACTOR_PARAM, ACTOR_PARAM.to_sym)
+      gid = actor.respond_to?(:to_global_id) ? actor.to_global_id.to_s : nil
+      gid ? params.merge(ACTOR_PARAM => gid) : params
+    rescue StandardError => e
+      Rails.logger.warn("[AgentRun] could not record the run's actor: #{e.class} - #{e.message}")
+      params
+    end
+
+    # The caller this run executes on behalf of.
+    #
+    # Set in memory for a synchronous run; rehydrated from the stored Global
+    # ID for one picked up by a worker. A Global ID that no longer resolves
+    # (the user was deleted) yields nil, so the run loses access rather than
+    # inheriting someone else's.
+    # @return [Object, nil]
+    def actor
+      return @actor if defined?(@actor)
+
+      @actor = locate_actor
+    end
+
+    attr_writer :actor
+
+    # Whether this run knows who it is for. A run with a recorded actor that
+    # no longer resolves is *not* unattributed — it is broken, and callers
+    # that care can tell the two apart.
+    # @return [Boolean]
+    def actor_recorded?
+      input_params.is_a?(Hash) && input_params[ACTOR_PARAM].present?
+    end
+
     # Whether runs can carry files in this host app: Active Storage loaded,
     # the macro applied, and its tables migrated. Never raises — a host
     # that skipped `rails active_storage:install` still runs agents, it
@@ -220,6 +269,16 @@ module ActionAgent
 
     private
 
+    def locate_actor
+      return nil unless actor_recorded?
+      return nil unless defined?(GlobalID::Locator)
+
+      GlobalID::Locator.locate(input_params[ACTOR_PARAM])
+    rescue StandardError => e
+      Rails.logger.warn("[AgentRun] could not resolve the run's actor: #{e.class} - #{e.message}")
+      nil
+    end
+
     def set_trace_id
       self.trace_id ||= SecureRandom.uuid
     end

data/app/services/action_agent/agent_execution_service.rb

@@ -45,6 +45,13 @@ module ActionAgent
       new(agent_record, run).call
     end
 
+    # Tool-call keywords that name the caller. The model's arguments and the
+    # run's actor share one keyword namespace by the time they reach a tool,
+    # so anything a model emits under these names is dropped before the call:
+    # an actor a model can name is not an authorization boundary, and the
+    # documents a model reads are attacker-reachable.
+    ACTOR_KEYWORDS = %i[actor current_user].freeze
+
     def initialize(agent_record, run)
       @agent_record = agent_record
       @run = run
@@ -52,6 +59,14 @@ module ActionAgent
       @event_sequence = 0
     end
 
+    # The caller this run executes on behalf of, or nil when it runs
+    # unattributed. Passed to every tool as +actor:+ — a host's SchemaTools
+    # scope block, Pundit policy or agent callback decides what that means.
+    # @return [Object, nil]
+    def actor
+      @run.actor
+    end
+
     # Emits a progress event on the run (streamed to the UI by pollers).
     # Never lets telemetry break execution.
     def emit_event(**kwargs)
@@ -266,6 +281,12 @@ module ActionAgent
     # execution) and recorded in @tool_invocations so tool names, arguments
     # and durations reach Traces and the persisted conversation.
     def execute_tool(name, **kwargs)
+      forged = kwargs.slice(*ACTOR_KEYWORDS)
+      if forged.any?
+        Rails.logger.warn("[AgentExecutionService] dropped caller-named arguments from #{name}: #{forged.keys.join(', ')}")
+        kwargs = kwargs.except(*ACTOR_KEYWORDS)
+      end
+
       # Record the absolute URL browse_page will actually fetch, not the bare
       # path the model passed — spans/events/persisted args stay unambiguous.
       kwargs[:url] = AgentToolbox.resolve_browse_url(kwargs[:url]) if name.to_s == "browse_page" && kwargs[:url]
@@ -309,7 +330,9 @@ module ActionAgent
         else
           # A tool one of the agent's own MCP servers serves is called there;
           # AgentToolbox answers the rest.
-          mcp_dispatcher.call(name, kwargs) || AgentToolbox.call(name, **kwargs)
+          # `actor:` comes from the run, never from kwargs (see
+          # ACTOR_KEYWORDS): it is who the run is for, not what it is about.
+          mcp_dispatcher.call(name, kwargs) || AgentToolbox.call(name, actor: actor, **kwargs)
         end
       rescue StandardError => e
         Rails.logger.warn("[AgentExecutionService] Tool #{name} failed: #{e.class} - #{e.message}")
@@ -529,7 +552,10 @@ module ActionAgent
         private :persist_tool_messages_to_context
       end
 
-      agent_class.public_send(action).generate_now
+      # `as` carries the caller onto the agent instance, so an agent's own
+      # before_action callbacks (ActiveAgent::Authorization) authorize
+      # against the same person the tools are scoped to.
+      agent_class.as(actor).public_send(action).generate_now
     end
 
     # Function-calling schemas for the agent's enabled tools that have