actionagent 1.8.0 → 1.9.0

data/app/services/action_agent/agent_scorecard.rb

@@ -32,7 +32,7 @@ module ActionAgent
       avg_durations = windowed.where.not(duration_ms: nil).group(:agent_id).average(:duration_ms)
       token_sums = windowed.group(:agent_id).sum("COALESCE(total_tokens, 0)")
       last_runs = AgentRun.where(agent_id: ids).group(:agent_id).maximum(:created_at)
-      eval_runs = latest_evaluation_runs(ids)
+      evals = evaluation_tiles(ids)
 
       trace_stats = telemetry_stats(ids, window_start)
       trace_last = unclaimed_traces(ids, nil).group(:agent_id).maximum(:timestamp)
@@ -44,7 +44,7 @@ module ActionAgent
         traced = stats[:count].to_i
         total = runs + traced
         succeeded = completed_counts[id].to_i + stats[:ok].to_i
-        eval_run = eval_runs[id]
+        eval_tile = evals[id] || {}
 
         {
           window_days: (WINDOW / 1.day).to_i,
@@ -55,9 +55,13 @@ module ActionAgent
           avg_duration_ms: blended_duration(avg_durations[id], runs, stats[:avg_duration], traced),
           tokens: token_sums[id].to_i + stats[:tokens].to_i,
           cost: costs[id],
-          eval_score: eval_run&.average_score,
-          eval_samples_passed: eval_run&.samples_passed,
-          eval_samples_evaluated: eval_run&.samples_evaluated,
+          # The evaluation tile: the pass rate pooled over the headline runs
+          # of the agent's evaluations that stand against its current version.
+          eval_score: eval_tile[:score],
+          eval_samples_passed: eval_tile[:passed],
+          eval_samples_evaluated: eval_tile[:evaluated],
+          eval_runs: eval_tile[:runs],
+          eval_not_counted: eval_tile[:not_counted],
           last_run_at: [ last_runs[id], trace_last[id] ].compact.max&.iso8601
         }
       end
@@ -170,22 +174,47 @@ module ActionAgent
     end
     private_class_method :blended_duration
 
-    # Latest complete evaluation run per agent. DISTINCT ON would do this in
-    # one pass on PostgreSQL, but it has no portable equivalent, so the
-    # highest id per agent (runs are only ever appended) is selected first
-    # and those rows fetched by id.
-    def self.latest_evaluation_runs(agent_ids)
-      evaluations = Evaluation.table_name
-      runs = EvaluationRun.table_name
-
-      newest = EvaluationRun.complete.joins(:evaluation)
-        .where(evaluations => { agent_id: agent_ids })
-        .group("#{evaluations}.agent_id")
-        .pluck(Arel.sql("#{evaluations}.agent_id"), Arel.sql("MAX(#{runs}.id)"))
-
-      by_run_id = newest.to_h { |agent_id, run_id| [ run_id, agent_id ] }
-      EvaluationRun.where(id: by_run_id.keys).index_by { |run| by_run_id[run.id] }
+    # The evaluation tile per agent: passes pooled over the headline runs
+    # (newest complete run) of its evaluations that are current against the
+    # agent's version or unrecorded, as the Evaluations page pools them —
+    # never a stale suite last run against older code, nor an archived one
+    # — so the tile is the pass rate of the agent as it is now, not a mean
+    # of criterion scores over whatever ran last.
+    #
+    #   { agent_id => { score:, passed:, evaluated:, runs:, not_counted: } }
+    #
+    # `score` is the pooled pass rate 0..1 (nil with nothing to count),
+    # `runs` the headline runs pooled and `not_counted` the evaluations
+    # left out as stale or archived. The newest complete run per evaluation
+    # is selected by id first (runs are only ever appended) and those rows
+    # fetched by id, which runs the same on every database.
+    def self.evaluation_tiles(agent_ids)
+      evaluations = Evaluation.where(agent_id: agent_ids).includes(:agent).to_a
+      return {} if evaluations.empty?
+
+      newest = EvaluationRun.complete.where(evaluation_id: evaluations.map(&:id)).group(:evaluation_id).maximum(:id)
+      runs = EvaluationRun.where(id: newest.values).includes(:agent_version).index_by(&:evaluation_id)
+      EvaluationStanding.preload(evaluations)
+
+      evaluations.group_by(&:agent_id).to_h do |agent_id, mine|
+        tile = { score: nil, passed: 0, evaluated: 0, runs: 0, not_counted: 0 }
+        mine.each do |evaluation|
+          run = runs[evaluation.id]
+          next unless run
+
+          unless evaluation.standing_info.with_headline(run).counted?
+            tile[:not_counted] += 1
+            next
+          end
+
+          tile[:runs] += 1
+          tile[:passed] += run.samples_passed.to_i
+          tile[:evaluated] += run.samples_evaluated.to_i
+        end
+        tile[:score] = (tile[:passed].to_f / tile[:evaluated]).round(3) if tile[:evaluated].positive?
+        [ agent_id, tile ]
+      end
     end
-    private_class_method :latest_evaluation_runs
+    private_class_method :evaluation_tiles
   end
 end

data/app/services/action_agent/agent_sync.rb

@@ -32,7 +32,8 @@ module ActionAgent
     end
 
     # @param agents [Array<Class>] ActiveAgent::Base subclasses
-    # @param owner [Object] the record agents and API keys scope to
+    # @param owner [Object, nil] the record agents and API keys scope to; nil
+    #   only in an install with no owner model, where agents have no owner
     # @param provider [String, Symbol, nil] defaults to the class's own
     # @param model [String, nil] defaults to the class's own
     def self.call(agents, owner:, provider: nil, model: nil)
@@ -48,7 +49,9 @@ module ActionAgent
 
     # @return [Result]
     def call
-      return Result.new(rows: [], errors: "An owner is required: the engine scopes agents to one.") if @owner.nil?
+      if @owner.nil? && Agent.owner_association
+        return Result.new(rows: [], errors: "An owner is required: the engine scopes agents to one.")
+      end
 
       rows = Agent.transaction { @agents.map { |klass| upsert(klass) } }
       Result.new(rows: rows, errors: nil)

data/app/services/action_agent/agent_tool_roster.rb

@@ -33,6 +33,14 @@ module ActionAgent
   # capabilities and the schema tools, +mcp_servers+ for services and their
   # per-server allow-lists (an entry with no +tools+ key offers everything
   # the server serves).
+  #
+  # Every tool row, and every tool a service lists, carries +approval_names+:
+  # the names Agent#approval_required_tools takes for it, which are the names
+  # the model calls it by. A capability names each function it exposes, and
+  # a schema or MCP tool its own name. The list is empty for a row whose
+  # calls the dashboard cannot hold for approval: the input tools, which ask
+  # on their own, and a tool the agent class declares in code, which its
+  # class runs.
   class AgentToolRoster
     AGENT_DEFINED = "agent_defined"
     DASHBOARD = "dashboard"
@@ -167,7 +175,8 @@ module ActionAgent
         usage_row(by_name[name]).merge(
           name: name,
           description: by_name[name]&.dig(:description),
-          enabled: allowed.nil? || allowed.include?(name)
+          enabled: allowed.nil? || allowed.include?(name),
+          approval_names: [ name ]
         )
       end
     end
@@ -200,7 +209,8 @@ module ActionAgent
           # window may still show it being called, but that is history. A
           # tool the agent class declares in code is offered by the class.
           enabled: schema ? saved_tools.include?(name) : true,
-          editable: schema
+          editable: schema,
+          approval_names: schema ? [ name ] : []
         )
       end
     end
@@ -222,15 +232,20 @@ module ActionAgent
           source: DASHBOARD,
           description: Agent::TOOL_DESCRIPTIONS[capability],
           enabled: saved_tools.include?(capability),
-          editable: true
+          editable: true,
+          approval_names: capability_functions(capability) - AgentToolbox::INPUT_FUNCTIONS
         )
       end
     end
 
+    def capability_functions(capability)
+      AgentToolbox::DEFINITIONS[capability]&.map { |definition| definition[:name].to_s } || []
+    end
+
     # A capability is one checkbox over the several functions it exposes
     # ("memory" is save_memory + recall_memory), so its usage is their sum.
     def capability_usage(capability)
-      names = (AgentToolbox::DEFINITIONS[capability]&.map { |definition| definition[:name].to_s } || []) + [ capability ]
+      names = capability_functions(capability) + [ capability ]
       rows = detected.select { |tool| names.include?(tool[:name]) }
       return nil if rows.empty?
 

data/app/services/action_agent/agent_toolbox.rb

@@ -50,6 +50,28 @@ module ActionAgent
       # Stateful: navigate changes what snapshot/click see, so these bypass
       # the toolbox result cache.
       "playwright_mcp" => [
+        # Not a browser action: the point where the agent stops and a person
+        # continues on the page it reached. AgentExecutionService answers it
+        # against the run's session recording (see #request_handoff there),
+        # which is why it has no FUNCTIONS entry.
+        {
+          name: "request_handoff",
+          description: "Hand the browser session to a person and stop. Call this the moment the page asks for something only its owner may give: payment details, a password, a one-time code, a consent. Pass the URL of the page you stopped on and the non-secret values you already entered, so the person can check them. After calling it, take no further browser actions; report where you stopped and what the person does next.",
+          parameters: {
+            type: "object",
+            properties: {
+              reason: { type: "string", description: "What the page is asking for, e.g. \"payment details\" or \"a login code sent by email\"" },
+              url: { type: "string", description: "The URL of the page the person continues on" },
+              form_values: {
+                type: "object",
+                description: "Values already entered, field label to value. Never a card number, password or code.",
+                additionalProperties: { type: "string" }
+              },
+              instructions: { type: "string", description: "One or two sentences on what the person should do next" }
+            },
+            required: [ "reason", "url" ]
+          }
+        },
         {
           name: "browser_navigate",
           description: "Open a URL in the managed browser. Returns a text snapshot of the page with element refs.",
@@ -77,6 +99,68 @@ module ActionAgent
             },
             required: [ "ref" ]
           }
+        },
+        {
+          name: "browser_type",
+          description: "Type text into an editable element from the latest snapshot: a text box, a search field. Set submit to press Enter afterwards.",
+          parameters: {
+            type: "object",
+            properties: {
+              ref: { type: "string", description: "Element ref from the snapshot" },
+              element: { type: "string", description: "Human-readable description of the element" },
+              text: { type: "string", description: "The text to type" },
+              submit: { type: "boolean", description: "Press Enter after typing" }
+            },
+            required: [ "ref", "text" ]
+          }
+        },
+        {
+          name: "browser_fill_form",
+          description: "Fill several form fields in one step. Each field names its ref from the latest snapshot, a label, its type and the value to enter; a checkbox takes true or false, a combobox the option's text.",
+          parameters: {
+            type: "object",
+            properties: {
+              fields: {
+                type: "array",
+                description: "The fields to fill",
+                items: {
+                  type: "object",
+                  properties: {
+                    ref: { type: "string", description: "Element ref from the snapshot" },
+                    name: { type: "string", description: "The field's label, e.g. Email" },
+                    type: { type: "string", enum: %w[textbox checkbox radio combobox slider], description: "The field's type" },
+                    value: { type: "string", description: "What to enter" }
+                  },
+                  required: [ "ref", "name", "type", "value" ]
+                }
+              }
+            },
+            required: [ "fields" ]
+          }
+        },
+        {
+          name: "browser_select_option",
+          description: "Choose an option in a dropdown from the latest snapshot.",
+          parameters: {
+            type: "object",
+            properties: {
+              ref: { type: "string", description: "Element ref from the snapshot" },
+              element: { type: "string", description: "Human-readable description of the element" },
+              values: { type: "array", items: { type: "string" }, description: "The option values or texts to select" }
+            },
+            required: [ "ref", "values" ]
+          }
+        },
+        {
+          name: "browser_press_key",
+          description: "Press a key in the browser, such as Enter, Escape, Tab or ArrowDown.",
+          parameters: {
+            type: "object",
+            properties: {
+              key: { type: "string", description: "The key to press" }
+            },
+            required: [ "key" ]
+          }
         }
       ],
       # Subject-bound like memory: routed by AgentExecutionService (needs the
@@ -148,6 +232,36 @@ module ActionAgent
           }
         }
       ],
+      # Asking a person mid-run. Each call pauses the run until the answer
+      # arrives (ActionAgent::InputRequest), so AgentExecutionService routes
+      # them, and they are NOT in FUNCTIONS below.
+      "ask" => [
+        {
+          name: "ask_user",
+          description: "Ask the user a question and wait for the answer before continuing. Pass options to have them " \
+            "pick one of a fixed set of answers. Use when you need information only the user has.",
+          parameters: {
+            type: "object",
+            properties: {
+              question: { type: "string", description: "The question, as the user should read it" },
+              options: { type: "array", items: { type: "string" }, description: "Answers to choose from; omit for a free-text answer" }
+            },
+            required: [ "question" ]
+          }
+        },
+        {
+          name: "request_approval",
+          description: "Ask the user to approve an action before you take it, and wait for their decision. Call it before " \
+            "any step with side effects the user has not already agreed to. Returns approved: true, or an error when declined.",
+          parameters: {
+            type: "object",
+            properties: {
+              action: { type: "string", description: "What you want to do, in one sentence the user can approve or decline" }
+            },
+            required: [ "action" ]
+          }
+        }
+      ],
       # Memory tools mirror solid_agent's HasMemory contract. They are NOT in
       # FUNCTIONS below — execution is subject-bound, so AgentExecutionService
       # routes them to the run's AgentMemory instead of this module.
@@ -179,6 +293,28 @@ module ActionAgent
       ]
     }.freeze
 
+    # Asks the user for a secret, such as an API key, delivered to the agent's
+    # server-side handler (ActionAgent::SecretRequests) and never to the
+    # model. Offered only to an agent with a registered handler, never
+    # through an agent's tools list, so it is not in DEFINITIONS.
+    REQUEST_SECRET_DEFINITION = {
+      name: "request_secret",
+      description: "Ask the user for a secret value, such as an API key or a password. The value is handed to the " \
+        "system without you ever seeing it; you receive only confirmation that it was provided.",
+      parameters: {
+        type: "object",
+        properties: {
+          name: { type: "string", description: "The secret's name, e.g. STRIPE_API_KEY" },
+          prompt: { type: "string", description: "What to tell the user about the value you need" }
+        },
+        required: [ "name", "prompt" ]
+      }
+    }.freeze
+
+    # The tools that pause a run to ask a person, routed by
+    # AgentExecutionService.
+    INPUT_FUNCTIONS = %w[ask_user request_approval request_secret].freeze
+
     # Function name => implementation method, for routing tool calls.
     FUNCTIONS = {
       "fetch_url" => :fetch_url,
@@ -188,24 +324,51 @@ module ActionAgent
       "browser_navigate" => :browser_navigate,
       "browser_snapshot" => :browser_snapshot,
       "browser_click" => :browser_click,
+      "browser_type" => :browser_type,
+      "browser_fill_form" => :browser_fill_form,
+      "browser_select_option" => :browser_select_option,
+      "browser_press_key" => :browser_press_key,
       "render_ui" => :render_ui
     }.freeze
 
     # Stateful tools whose results must never be replayed from cache — and
     # render_ui, whose result is the call itself, so there is nothing to
-    # replay.
-    UNCACHED_FUNCTIONS = %w[browser_navigate browser_snapshot browser_click render_ui].freeze
+    # replay, and the tools whose result is a person's answer.
+    UNCACHED_FUNCTIONS = (%w[
+      browser_navigate browser_snapshot browser_click browser_type browser_fill_form
+      browser_select_option browser_press_key render_ui
+    ] + INPUT_FUNCTIONS).freeze
+
+    # The group whose tools drive the process-wide browser
+    # (PlaywrightMCPClient), and those tools. A run against a sandbox with a
+    # running browser gets that browser's tools instead, and a multi-tenant
+    # install never offers or calls these: every tenant's runs would share
+    # one browser.
+    SHARED_BROWSER_GROUP = "playwright_mcp"
+    SHARED_BROWSER_FUNCTIONS = DEFINITIONS.fetch(SHARED_BROWSER_GROUP).map { |definition| definition[:name] }.freeze
 
     # Hosts browse_page may fetch — the platform's own trusted docs.
     BROWSE_ALLOWED_HOSTS = %w[docs.activeagents.ai].freeze
 
     class << self
       # Tool definitions for the subset of an agent's enabled tools that have
-      # server-side implementations.
-      def definitions_for(tool_names)
-        Array(tool_names).flat_map do |name|
-          DEFINITIONS[name.to_s] || schema_tool_definitions(name.to_s)
-        end
+      # server-side implementations. The shared browser's are left out when
+      # +browser_attached+ (the run reaches its sandbox's browser, which
+      # serves tools of the same names) or when shared_browser? is false.
+      # Never request_secret, whatever the list names.
+      def definitions_for(tool_names, browser_attached: false)
+        names = Array(tool_names).map(&:to_s)
+        names -= [ SHARED_BROWSER_GROUP ] if browser_attached || !shared_browser?
+
+        names.flat_map do |name|
+          DEFINITIONS[name] || schema_tool_definitions(name)
+        end.reject { |definition| definition[:name].to_s == REQUEST_SECRET_DEFINITION[:name] }
+      end
+
+      # Whether runs may use the process-wide browser: never in a
+      # multi-tenant install.
+      def shared_browser?
+        !ActionAgent.multi_tenant?
       end
 
       def function?(name)
@@ -230,6 +393,9 @@ module ActionAgent
       # instead of re-running the side effect.
       def call(name, **kwargs)
         return { error: "Unknown tool: #{name}" } unless function?(name)
+        if SHARED_BROWSER_FUNCTIONS.include?(name.to_s) && !shared_browser?
+          return { error: "#{name} needs a browser: start the browser of the sandbox this agent runs against" }
+        end
 
         # Who the call is for is never one of the call's arguments: it comes
         # off here, before a tool sees them. That keeps a built-in from
@@ -354,8 +520,48 @@ module ActionAgent
         playwright_mcp("browser_snapshot", {})
       end
 
-      def browser_click(ref:, element: nil)
-        playwright_mcp("browser_click", { ref: ref, element: element || ref })
+      def browser_click(ref: nil, target: nil, element: nil, button: nil)
+        playwright_mcp("browser_click", browser_target(ref || target, element).merge({ button: button }.compact))
+      end
+
+      def browser_type(text:, ref: nil, target: nil, element: nil, submit: nil, slowly: nil)
+        arguments = browser_target(ref || target, element).merge({ text: text.to_s, submit: submit, slowly: slowly }.compact)
+        playwright_mcp("browser_type", arguments)
+      end
+
+      def browser_fill_form(fields:)
+        normalized = Array(fields).map do |field|
+          field = field.to_h.transform_keys(&:to_s)
+          {
+            target: (field["target"] || field["ref"]).to_s,
+            name: field["name"].to_s,
+            type: field["type"].presence || "textbox",
+            value: field["value"].to_s
+          }
+        end
+        raise ArgumentError, "every field needs a ref" if normalized.any? { |field| field[:target].blank? }
+
+        playwright_mcp("browser_fill_form", { fields: normalized })
+      end
+
+      def browser_select_option(values:, ref: nil, target: nil, element: nil)
+        playwright_mcp("browser_select_option", browser_target(ref || target, element).merge(values: Array(values).map(&:to_s)))
+      end
+
+      def browser_press_key(key:)
+        playwright_mcp("browser_press_key", { key: key.to_s })
+      end
+
+      # Playwright MCP addresses an element by +target+ — a ref from the
+      # latest snapshot, or a selector — and names it in +element+ for the
+      # permission prompt it may show. Earlier releases of the server called
+      # the ref +ref+, and that is still what the tool schemas ask the model
+      # for, so both spellings are accepted here and sent as the server now
+      # expects.
+      def browser_target(target, element)
+        raise ArgumentError, "an element ref from the snapshot is required" if target.blank?
+
+        { target: target.to_s, element: (element.presence || target).to_s }
       end
 
       SNAPSHOT_LINK = /\[Snapshot\]\(([^)]+)\)/

data/app/services/action_agent/browser_live_ticket.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require "base64"
+require "json"
+require "openssl"
+
+module ActionAgent
+  # Used to issue the tickets that let a dashboard viewer into a sandbox
+  # browser's live view. The viewer's page sends the ticket as the first
+  # message on the live view's WebSocket, and the browser sidecar checks it
+  # (browser-sidecar/lib/live-ticket.mjs), so a ticket never travels in a URL.
+  #
+  # A ticket is base64url JSON claims, a dot, and the base64url HMAC-SHA256
+  # of that first part. The key is the HMAC-SHA256 of CONTEXT under the
+  # browser's token, which the sidecar was given on stdin when it started:
+  # a ticket opens only the browser it was issued for, and only until that
+  # browser stops. The sidecar accepts each ticket once, within LIFETIME.
+  #
+  # Claims:
+  #   v     1
+  #   sid   the sandbox session
+  #   sub   the user it was issued to, as a String, or nil without one
+  #   name  their name, shown to other viewers ("held by Ada"), or nil
+  #   mode  "view" to watch, "control" to also take over
+  #   iat   when it was issued, in epoch seconds
+  #   exp   when it expires, in epoch seconds
+  #   jti   its unique id
+  class BrowserLiveTicket
+    CONTEXT = "activeagents/browser-live-ticket/v1"
+    MODES = %w[view control].freeze
+    # The sidecar refuses a ticket issued for longer than 60 seconds.
+    LIFETIME = 30.seconds
+    MAX_NAME_LENGTH = 80
+
+    # Returns { ticket:, mode:, expires_at: } for +sandbox+'s running browser.
+    #
+    # @param user [Object, nil] the viewer, whose id and name the ticket carries
+    # @param mode [String] one of MODES
+    # @raise [ArgumentError] for an unknown mode, or a sandbox whose browser
+    #   has no token
+    def self.issue(sandbox, user:, mode:, now: Time.current, jti: SecureRandom.urlsafe_base64(24))
+      raise ArgumentError, "mode must be one of #{MODES.join(', ')}" unless MODES.include?(mode)
+      raise ArgumentError, "The sandbox's browser has no token" if sandbox.browser_token.blank?
+
+      issued_at = now.to_i
+      claims = {
+        v: 1,
+        sid: sandbox.session_id,
+        sub: user&.id&.to_s,
+        name: display_name(user),
+        mode: mode,
+        iat: issued_at,
+        exp: issued_at + LIFETIME.to_i,
+        jti: jti
+      }
+      { ticket: sign(sandbox.browser_token, claims), mode: mode, expires_at: Time.zone.at(claims[:exp]) }
+    end
+
+    # The ticket for +claims+, signed with the key derived from +token+.
+    def self.sign(token, claims)
+      payload = Base64.urlsafe_encode64(JSON.generate(claims), padding: false)
+      signature = OpenSSL::HMAC.digest("SHA256", key(token), payload)
+      "#{payload}.#{Base64.urlsafe_encode64(signature, padding: false)}"
+    end
+
+    def self.key(token)
+      OpenSSL::HMAC.digest("SHA256", token, CONTEXT)
+    end
+
+    def self.display_name(user)
+      return nil unless user
+
+      name = user.try(:display_name).presence || user.try(:name).presence || user.try(:email_address).presence || user.try(:email).presence
+      name&.to_s&.truncate(MAX_NAME_LENGTH)
+    end
+    private_class_method :key, :display_name
+  end
+end