activeagent 1.5.2 → 1.6.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 73e63c87b700b6dec4e3410ae0547ff1c02714fbe79b24175447fb5638a9fe3b
-  data.tar.gz: ef361dc3bb7dcab252c0fadf1fb526e689b97b21386a2d50b6ba6eb96a84100a
+  metadata.gz: b14c71e437e0c5701b6300861adb5d8b79eba328602e255b38928e6030584a2b
+  data.tar.gz: c5eeeedce5730d88609b5131304571f9d7ecc12d3177ada460de7a4dd56ad61d
 SHA512:
-  metadata.gz: 7ed21c4a284e17d0014ef83b09fc56741b96cbb83f219f38dc3e8ad87f511f9ed5b3d902e1b1e9c7e4db11c83bce07ed0effbb2f44d85c35d0da4738598744b3
-  data.tar.gz: c3634cfbe8e532889e2ef82b7080b30f0233a0faf1e81b5c37995949a8c7a6d5e6ebf9e3800e39457c54de3803d22b3545d4606d448867a777915cabf1a39b15
+  metadata.gz: d76b024171c0a84e4ecc6f6618ccb92d1e94a215f15e15839e8b78b37c8bcd6a312626b8dda996cca23bb2ebcab325fc08fab289689d66143855fa0c372ffb40
+  data.tar.gz: 02605c62c4d22bc001462ee13451fce5f578cb43adb8f9380c8f116ef589629cafb175e10ce019fa073b9086382c2e8dd09bb03d9aab52813f75852a27e43aeb

data/CHANGELOG.md

@@ -7,6 +7,272 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.6.2] - 2026-09-16
+
+Releases `activeagent` and `actionagent` 1.6.2 from one tag.
+
+Agents gain releases: a digest of everything the model is given, cut on
+deploy and pinned to every trace, run and evaluation run, so a score is a
+statement about a specific release and a regression is attributable to the
+change that caused it. Around it, five dashboard fixes: an evaluation
+created on MySQL can be run, the Tools tab reads the same `agent.tools` the
+runner does, a container-valued query parameter is coerced instead of
+raising, a recording's detail response no longer carries the visitor's
+cookies and web storage, and the MCP endpoint answers an unsupported method with 405
+instead of the dashboard page. `sign_in_path` and `sign_out_path` are now
+documented.
+
+Upgrading: the install generator emits a new `add_agent_releases` migration
+(guarded column by column); run it. Cutting a release is
+`rake action_agent:agents:release[REVISION]` in the deploy.
+
+### Added
+
+- **Agents have releases, and every trace, run and evaluation says which one
+  it ran under.** `ActiveAgent::Release` gives each agent class a digest of
+  what the model is given — provider and model, generation options minus
+  credentials, the actions, the prompt templates on disk, and the tools and
+  delegations it declares — so two deploys of the same agent share a digest
+  and any change to those inputs is a new one, with no number to bump.
+  `ActiveAgent::Release.revision` carries the deploy alongside (a git SHA;
+  read from `SERVICE_VERSION`, `GIT_SHA`, `KAMAL_VERSION` and friends when
+  not set). The instrumentation stamps `agent.version` and `agent.revision`
+  on every generation's root span, and every trace gets `service.version`.
+  In the dashboard, `rake action_agent:agents:release[REVISION]` cuts an
+  `AgentVersion` for each agent whose code changed since the last release —
+  idempotent, so it belongs in the deploy — `rake action_agent:agents:versions`
+  lists them, and `Agent#record_release!` is the call behind both for a host
+  that syncs agents its own way. Traces are pinned to the release their root
+  span names, runs and evaluation runs to the version current when they
+  started (`agent_version_id` on all three; the install generator emits the
+  migration). A version's JSON carries `release`, `release_digest` and
+  `revision`, so the Versions tab tells a deploy from an edit. For that to
+  reach a host's own agents, a trace from a class the host mirrors into the
+  dashboard is now attributed to that mirror — the registrar matched only on
+  service, class *and* action, so every code-path trace registered an
+  observed per-action twin beside the synced record and could never be
+  pinned to its release.
+
+### Fixed
+
+- **An evaluation created on MySQL can be run.** MySQL cannot give a JSON
+  column a default, so an evaluation saved there without `config` read it
+  back as `nil`, and `compare_models` raised before the runner did anything
+  else. `config` and `criteria` now read as the empty value their column
+  default supplies on other databases. (#417)
+- **The Tools tab now says which schema tools an agent is offered, and
+  lets you change it.** The editor listed every schema tool as enabled and
+  read-only whatever `agent.tools` held — *"a checkbox that cannot add or
+  remove the tool is a control that changes nothing"* — while evaluations,
+  dashboard runs and the MCP facade offered exactly what that column named.
+  An agent whose roster had been emptied over the API ran a suite with no
+  tools (1/8, `expected tool not called ×6`) under a tab reading "12
+  enabled". A schema tool's row now reads the roster and is switchable, and
+  every schema tool the host declares has a row, off unless the roster names
+  it — any agent may enable any of them, and a tool switched off has to keep
+  its row to be switched back on. A tool the agent class declares in code is
+  still reported rather than selected: the class offers it, and no checkbox
+  could change that.
+- **A container-valued query parameter no longer 500s the dashboard API.**
+  `page`, `per_page`, `days`, `minutes`, `limit` and `after_sequence` were
+  read with `to_i`, which neither an Array (`minutes[]=1&minutes[]=2`) nor a
+  nested object (`page[x]=1`) answers. `Api::BaseController` now coerces
+  them: a multi-valued parameter means its first value, a nested object falls
+  back to the default, and the clamps that bounded the number still apply.
+  `sandboxes#compare` answers a `providers` value that is not a list of
+  names with a 400 instead of a `NoMethodError`.
+- **A session recording's `show` no longer returns the visitor's cookies and
+  web storage.** Every other read path redacted the handoff state, but the
+  detail response carried `cookies`, `session_storage` and `local_storage`
+  unscrubbed, both as its own key and nested inside `metadata`. Both are now
+  stripped; only `#handoff` returns them, to the recording's owner. (#456)
+
+## [1.6.1] - 2026-09-16
+
+Releases `activeagent` and `actionagent` 1.6.1 from one tag.
+
+A patch for two defects that share a failure mode: each one turns a broken
+run into a plausible-looking success rather than an error. A date filter that
+matched nothing reported zero instead of raising, and an agent reported that
+zero as fact; telemetry that was enabled but never instrumented wrote no
+traces while every configuration signal read healthy. Neither surfaced in a
+test suite, because neither produces a failure — only a confident wrong
+answer and an empty table.
+
+No new public surface and no behaviour change for anything that was already
+working, so a patch under semver. Suites that filter on a date column will
+report different — correct — numbers after upgrading; read the first run as a
+corrected baseline.
+
+### Fixed
+
+- **A range filter on a `SchemaTools` column no longer matches nothing and
+  reports zero.** `permitted_filters!` validated the column against the
+  allowlist but passed the value through untouched, so a range hash reached
+  `where` unrecognized and Rails compiled `where(due_date: {"before" => x})`
+  to `due_date = NULL` — a predicate that matches no row. The tool returned
+  `{count: 0}` with no error and the model read it as a truthful empty
+  answer: "0 overdue tickets" against a database holding four. Equality
+  filters were unaffected, which is why this went unnoticed. Comparisons are
+  now built through Arel with the column's own type cast, under the operators
+  `before`, `after`, `lt`, `lte`, `gt`, `gte`, `on_or_before` and
+  `on_or_after`; two bounds may be given together to express a window; and an
+  operator outside that set raises `UnpermittedAttribute` rather than
+  returning zero, consistent with how an undeclared column is already
+  rejected. Ranges are offered for date, datetime, time and numeric columns
+  only — a lexical `>` on a name column answers a question nobody asked.
+- **A range filter is now discoverable.** `filter_properties` described a date
+  column as a bare `{type: "string", format: "date"}`, so the tool surface
+  could not express "before today" at all and a model asking the question
+  correctly still had no way to ask it. Comparable columns are now offered as
+  `anyOf: [scalar, range object]`, with the operator roster in the schema.
+- **Telemetry enabled from a host app's initializer now installs
+  instrumentation.** The railtie prepended `GenerationInstrumentation` only
+  when `Telemetry.enabled?` was already true as railties ran — before
+  `config/initializers/*.rb`. An app that configures telemetry in its own
+  initializer, which is what the documentation shows, was therefore never
+  instrumented: `enabled?` answered true, `local_storage` was on, the trace
+  model resolved and the store lambda worked when called directly, and no
+  generation ever produced a span to store. `configure` now installs as well
+  when the resulting configuration is enabled; `instrument_telemetry!` is
+  idempotent, so the railtie path and the configure path cannot
+  double-prepend and initializer order stops mattering.
+
+## [1.6.0] - 2026-09-14
+
+Releases `activeagent` and `actionagent` 1.6.0 from one tag.
+
+A minor, not a patch. The cycle that began after 1.5.2 gives an agent a
+caller — `current_user`, carried from whatever authenticated the call into
+every `before_action`, every tool, every delegated sub-agent, every run over
+MCP and every evaluation replay — so an authorization gem has something to
+decide against. Around it: schema tools defined at runtime rather than only
+in a file, a generator that writes the first one, those tools served
+directly over MCP, and an evaluation that calls a fabricated answer a fault
+instead of grading it as an honest gap. That is new public surface in both
+gems, which is a minor under semver even though 1.5.2 shipped a feature as a
+patch.
+
+Two notes for upgrades. `tools_succeeded` is now awarded only for a tool the
+scenario expected, so a suite that was quietly scoring wrong-tool runs as
+partial successes will report lower — read the first run as a corrected
+baseline. And `actor:` is now stripped from tool arguments and from
+`params[params][actor]`: the caller is a property of the run, set once by
+whatever authenticated it, and can no longer be named by the model or by a
+client.
+
+The engine's floor on the framework (`activeagent >= 1.4`) is unchanged and
+still correct: 1.6.0 satisfies it.
+
+### Added
+
+- **An evaluation replay runs as the evaluation's owner.** The scenario runner
+  handed `Agent#test_execute` no caller, so every tool a replay called ran
+  unattributed and a host scope answered empty — the suite graded an agent
+  that never saw a row. When agents are owned per user, a replay now runs as
+  the user who owns the evaluation, as a run over MCP runs as the key's
+  owner. A multi-tenant install still replays unattributed (an account is who
+  is billed, not who is allowed) unless a host adapter runs the suite itself.
+- **The MCP facade serves the host's schema tools directly.** `tools/list`
+  at `POST <mount>/mcp` now offers every tool the dashboard's discovered
+  `ActiveAgent::SchemaTools` classes generate — `find_<records>`,
+  `count_<records>`, `get_<record>` — beside the `run_<slug>` agents, each
+  with its own parameter schema, and `tools/call` runs one as the key's
+  caller through the host's own scope, exactly as it would inside an agent
+  run. A client that only needs the rows no longer has to ask an agent for
+  them. A boundary violation is a tool result with `isError`, a refusal from
+  the host's scope is a JSON-RPC `-32003`, and neither the execution switch
+  nor the execution quota applies, because nothing generates. Set
+  `ActionAgent.mcp_schema_tools = false` to keep the tools reachable only
+  through agents. Closes #439.
+- **A delegated run inherits its parent's caller.** `delegate_to` hands the
+  sub-agent the parent's `current_user` before its action runs, so its own
+  `before_action` callbacks and any scope its tools read through decide
+  against the same person. A parent authorized as one user no longer hands
+  its specialists an unattributed run — which a correctly written host scope
+  reads as "no access", a wrong answer wearing a right one's clothes. A
+  parent with no caller still delegates an unattributed run, never someone
+  else's.
+- **`rails generate active_agent:schema_tools Reservation`** writes a starter
+  `ActiveAgent::SchemaTools` class under `app/agent_tools`. It exposes nothing
+  beyond `id` until a column is moved into `filterable` or `returns`; every
+  column the model has is listed, commented out, with its type, so the
+  allowlist is a review step rather than a blank page, and columns that look
+  like secrets are left off the list. Reads are scoped through
+  `<Model>Policy::Scope` when it exists (`--policy` / `--no-policy` decide
+  explicitly). This is #440's second option: the roster is still declared,
+  once, but the declaration is no longer written from scratch. (#440)
+- **An agent knows who it is running for, so an authorization gem has
+  something to decide against.** `ActiveAgent::Base#current_user` carries the
+  caller, assigned by whatever authenticated the call
+  (`MyAgent.as(current_user).ask(...)`) and readable from every
+  `before_action`, so Pundit, CanCanCan or Action Policy authorize an agent
+  the way they authorize a controller. A refusal inside a tool call is
+  returned to the model as `{ error: ... }` so it can say it is not allowed;
+  a refusal anywhere else is raised to the caller. `denies_with` names a
+  gem's own error as a refusal.
+- **The dashboard fills that seam.** A run records the caller that started it
+  (a Global ID, so a worker on another machine authorizes as the same
+  person), passes it to every tool as `actor:`, and runs the agent through
+  `as(actor)` — which is what a `SchemaTools` `scope` block has been waiting
+  for since 1.5.0. `ActionAgent.agent_actor_resolver` overrides who that is.
+- **Agents reached over MCP run as the key's caller** rather than
+  unattributed, and an agent that refuses answers as a JSON-RPC error
+  (`-32003`) instead of as an empty result.
+- **Schema tools can be defined at runtime.** `ActiveAgent::SchemaTools.define(Reservation,
+  filterable:, returns:, scope: | policy:)` builds the same bounded roster a
+  file under `app/agent_tools` would — same allowlists, same `call`, named
+  `ReservationTools` for logs — from a declaration held anywhere: a table, a
+  dashboard form, a test. The class is registered under its model and a
+  redefinition replaces the previous one, so a registry rebuilt on every
+  change holds one class per model; `undefine` drops it. The dashboard
+  discovers registry entries beside the files and lets a runtime definition
+  supersede a file for the same model. What is persisted, and where, stays the
+  host's decision; this is the seam a persisted declaration builds on. (#441)
+- **A fabricated answer is now a fault.** `Diagnosis` raises `ungrounded_answer`
+  when an agent that had tools called none, did not say it could not answer,
+  and still stated specifics — a count, a record id, a date — that no tool
+  supplied. Where the scenario names an expected tool, `expected_tool_not_called`
+  says the same thing in its summary and carries `ungrounded: true`, so an
+  invented answer no longer reads like an honest gap. Both reach the judge,
+  which is what turns them into a suggested tool. An agent with no tools at all
+  is not flagged: it answers from its instructions by design, and whether that
+  is acceptable is the judge's grade, not a mechanical one. (#433)
+
+### Changed
+
+- **A wrong tool no longer outscores no tool.** `tools_succeeded` is awarded
+  only for a tool the scenario expected (or any tool when it expects none):
+  a tool that ran without erroring was evidence of the task only by accident,
+  and a scenario that called the wrong tool scored higher than one that called
+  nothing. (#433)
+- **The judge reads more of a scenario's notes** — 1,500 characters rather
+  than 300 — because a suite's notes are often its rubric and the "must not"
+  clause tends to come last. (#433)
+
+### Fixed
+
+- **The caller can no longer be named by the model, or by the client.**
+  `actor:` reached `AgentToolbox.call` in the same keyword namespace as the
+  arguments a provider parsed out of a model's tool call, and
+  `params[params][actor]` in an execute request would have won over the
+  controller's own. Both are now stripped: the caller is a property of the
+  run, set once by whatever authenticated it. Scoped `SchemaTools` reads are
+  also excluded from the tool-result cache, so one caller's rows are never
+  replayed for the next.
+- **A superseded runtime tool class is no longer offered twice.** Discovery
+  read every `SchemaTools` subclass out of `descendants`, where a class built
+  at runtime stays until it is collected, so rebuilding a model's tools
+  accumulated stale duplicates. Runtime-built classes are now read from the
+  registry only. (#441)
+- **A persisted model selection re-runs under the provider it ran under.**
+  `Evals::ModelSpec.parse_all` re-parsed a round-tripped spec from its label,
+  so `anthropic/claude-sonnet-4.5` run through OpenRouter came back as
+  Anthropic's own `claude-sonnet-4.5` as soon as that provider's gem was
+  installed — and the re-run failed for want of an Anthropic credential. A
+  hash naming both `provider` and `model` is now rebuilt as it was; a bare
+  label is still parsed. The dashboard's "re-run" of a saved selection is
+  the path this fixes.
 ## [1.5.2] - 2026-09-11
 
 Releases `activeagent` and `actionagent` 1.5.2 from one tag.

data/lib/active_agent/base.rb

@@ -4,6 +4,7 @@ require "active_support/core_ext/hash/except"
 require "active_support/core_ext/module/anonymous"
 require "active_support/core_ext/string/inflections"
 
+require "active_agent/concerns/authorization"
 require "active_agent/concerns/callbacks"
 require "active_agent/concerns/delegation"
 require "active_agent/concerns/observers"
@@ -11,6 +12,7 @@ require "active_agent/concerns/parameterized"
 require "active_agent/concerns/preview"
 require "active_agent/concerns/provider"
 require "active_agent/concerns/queueing"
+require "active_agent/concerns/release"
 require "active_agent/concerns/rescue"
 require "active_agent/concerns/streaming"
 require "active_agent/concerns/tooling"
@@ -43,15 +45,22 @@ module ActiveAgent
     include AbstractController::Caching
 
     include Callbacks
+    # After Rescue: the refusal handler is registered with rescue_from.
     include Delegation
     include Parameterized
     include Provider
     include Queueing
+    include Release
     include Rescue
     include Streaming
     include Tooling
     include View
 
+    # Last of the behaviour concerns: its rescue_from must sit on top of the
+    # handlers an agent registers for its own authorization gem, so a host
+    # mapping Pundit::NotAuthorizedError keeps deciding what a refusal means.
+    include Authorization
+
     include Observers
     include Previews
 

data/lib/active_agent/concerns/authorization.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+module ActiveAgent
+  # Raised when an agent refuses a call on the current caller's behalf.
+  #
+  # Hosts usually raise their authorization gem's own error instead
+  # (+Pundit::NotAuthorizedError+, +CanCan::AccessDenied+) and name it with
+  # {Authorization::ClassMethods#denies_with}; this exists so an agent that
+  # has no gem still has something to raise, and so the framework has one
+  # class to describe a refusal with.
+  class NotAuthorized < StandardError
+    # @return [Symbol, String, nil] the action or tool that was refused
+    attr_reader :action
+    # @return [Object, nil] the caller the refusal was decided against
+    attr_reader :actor
+
+    def initialize(message = nil, action: nil, actor: nil)
+      @action = action
+      @actor = actor
+      super(message || default_message)
+    end
+
+    private
+
+    def default_message
+      who = actor.nil? ? "an unauthenticated caller" : "the current caller"
+      what = action ? "`#{action}`" : "this agent"
+      "#{who} is not allowed to call #{what}"
+    end
+  end
+
+  # Carries the caller an agent runs on behalf of, so an agent's callbacks can
+  # authorize with whatever the host app already uses.
+  #
+  # An agent reached over MCP, from a dashboard run, or from a controller is
+  # acting *for someone*. Without that someone, an authorization gem has
+  # nothing to decide against: a Pundit scope handed +nil+ correctly resolves
+  # to the empty set, so a perfectly wired agent answers "there are no
+  # tickets" instead of refusing — a wrong answer that reads like a true one.
+  #
+  # == The seam
+  #
+  # {#current_user} is assigned by whatever authenticated the call and is
+  # readable from every callback and action:
+  #
+  #   class TicketAgent < ApplicationAgent
+  #     before_action :authorize_tickets!
+  #
+  #     def find_tickets(**filters)
+  #       TicketTools.call("find_tickets", actor: current_user, **filters)
+  #     end
+  #
+  #     private
+  #
+  #     def authorize_tickets!
+  #       raise ActiveAgent::NotAuthorized.new(action: action_name, actor: current_user) unless
+  #         TicketPolicy.new(current_user, Ticket).index?
+  #     end
+  #   end
+  #
+  #   TicketAgent.as(current_user).find_tickets.generate_now
+  #
+  # Any gem works, because the framework never interprets the actor — Pundit's
+  # +authorize+/+policy_scope+, CanCanCan's +can?+, Action Policy's
+  # +authorize!+, or a plain predicate. +before_action+ is the same
+  # +AbstractController+ chain a controller uses, including +only:+/+except:+,
+  # so a roster can be authorized tool by tool.
+  #
+  # == It is never model input
+  #
+  # The actor is an attribute of the run, set out of band by the caller. It is
+  # deliberately not part of +params+ and not a tool argument: everything a
+  # model emits is attacker-reachable through the documents it reads, and an
+  # actor a model can name is not an authorization boundary. Assigning it is
+  # the caller's job, once, before the generation starts.
+  #
+  # == What a refusal does
+  #
+  # A refusal inside a *tool call* is returned to the model as an error result
+  # ({ error: ... }), so it can tell the user it is not allowed to look rather
+  # than dying mid-run or, worse, reporting an empty result set as fact. A
+  # refusal anywhere else — the action the caller asked for — is raised, so
+  # the MCP client or controller that asked gets an error instead of an
+  # answer that silently covers less ground than it appears to.
+  #
+  # {ClassMethods#denies_with} is how a gem's own error joins that rule:
+  #
+  #   class ApplicationAgent < ActiveAgent::Base
+  #     denies_with Pundit::NotAuthorizedError
+  #   end
+  module Authorization
+    extend ActiveSupport::Concern
+
+    included do
+      # The caller this generation runs on behalf of, or nil when it runs
+      # unattributed. Whatever the host uses as an actor: a User, an API
+      # key's owner, a service account.
+      attr_accessor :current_user
+
+      # Exception classes that mean "the caller may not do this". Declared
+      # rather than guessed: only the host knows which of its errors are a
+      # refusal and which are a bug.
+      class_attribute :authorization_errors, instance_writer: false,
+        default: [ ActiveAgent::NotAuthorized ].freeze
+    end
+
+    class_methods do
+      # Treats +classes+ as refusals, so raising one inside a tool call
+      # reports to the model instead of ending the run.
+      #
+      # @param classes [Array<Class>] exception classes from an authorization gem
+      # @return [Array<Class>] every class now treated as a refusal
+      #
+      # @example
+      #   denies_with Pundit::NotAuthorizedError, CanCan::AccessDenied
+      def denies_with(*classes)
+        self.authorization_errors = (authorization_errors | classes.flatten).freeze
+      end
+
+      # Runs the agent on behalf of +actor+.
+      #
+      # @param actor [Object, nil] the caller, or nil to run unattributed
+      # @return [ActiveAgent::Parameterized::Agent] a proxy carrying the actor
+      #
+      # @example
+      #   SupportAgent.as(current_user).answer(question).generate_now
+      #
+      # @example With parameters
+      #   SupportAgent.as(current_user).with(locale: :en).answer(question)
+      def as(actor)
+        ActiveAgent::Parameterized::Agent.new(self, {}, actor: actor)
+      end
+    end
+
+    # Whether a refusal right now would be reported to the model rather than
+    # raised to the caller.
+    # @return [Boolean]
+    def tool_call?
+      @_active_agent_tool_call ||= false
+    end
+
+    # Marks the block as a tool call, so a refusal inside it becomes a result
+    # the model can read. Nested calls keep the outer marking.
+    # @api private
+    def with_tool_call
+      previous = @_active_agent_tool_call
+      @_active_agent_tool_call = true
+
+      result = yield
+      # A host's own rescue_from handler runs inside `process`, and
+      # ActiveSupport::Rescuable answers with the exception itself — so a
+      # refusal arrives either raised or returned, and both mean the same
+      # thing here.
+      refusal?(result) ? refused(result) : result
+    rescue *authorization_errors => exception
+      refused(exception)
+    ensure
+      @_active_agent_tool_call = previous
+    end
+
+    private
+
+    def refusal?(value)
+      value.is_a?(Exception) && authorization_errors.any? { |klass| value.is_a?(klass) }
+    end
+
+    def refused(exception)
+      logger&.info("[#{self.class.name}] refused #{action_name}: #{exception.message}")
+      { error: exception.message }
+    end
+  end
+end

data/lib/active_agent/concerns/parameterized.rb

@@ -110,9 +110,28 @@ module ActiveAgent
     class Agent
       # @param agent [Class] the agent class to proxy
       # @param params [Hash] the parameters to pass to agent instances
-      def initialize(agent, params)
+      # @param actor [Object, nil] the caller the generation runs on behalf
+      #   of (see ActiveAgent::Authorization). Kept beside params rather than
+      #   in them: params reach templates and are part of what a generation
+      #   is *about*, while the actor is who it is *for*, and only the caller
+      #   may say.
+      def initialize(agent, params, actor: nil)
         @agent = agent
         @params = params
+        @actor = actor
+      end
+
+      # Adds parameters, keeping the actor. Lets +as+ and +with+ chain in
+      # either order.
+      # @return [ActiveAgent::Parameterized::Agent]
+      def with(params = {})
+        self.class.new(@agent, @params.merge(params), actor: @actor)
+      end
+
+      # Runs on behalf of +actor+, keeping any parameters.
+      # @return [ActiveAgent::Parameterized::Agent]
+      def as(actor)
+        self.class.new(@agent, @params, actor: actor)
       end
 
       # Intercepts calls to agent action methods and creates parameterized generations.
@@ -124,7 +143,9 @@ module ActiveAgent
       # @raise [NoMethodError] if the method doesn't exist on the agent class
       def method_missing(method_name, ...)
         if @agent.public_instance_methods.include?(method_name)
-          ActiveAgent::Parameterized::Generation.new(@agent, method_name, @params, ...)
+          ActiveAgent::Parameterized::Generation.new(@agent, method_name, @params, ...).tap do |generation|
+            generation.actor = @actor
+          end
         else
           super
         end
@@ -146,6 +167,17 @@ module ActiveAgent
     #
     # @api private
     class Generation < ActiveAgent::Generation
+      # @param agent_class [Class] the agent class
+      # @param action [Symbol, String] the action method name
+      # @param params [Hash] the parameters to set on the agent instance
+      # @param args [Array] additional arguments for the action method
+      # The caller the generation runs on behalf of. Assigned after
+      # construction rather than taken as a keyword, because the action's own
+      # arguments are forwarded here and an actor keyword would collide with
+      # one of the same name.
+      # @return [Object, nil]
+      attr_accessor :actor
+
       # @param agent_class [Class] the agent class
       # @param action [Symbol, String] the action method name
       # @param params [Hash] the parameters to set on the agent instance
@@ -163,6 +195,7 @@ module ActiveAgent
       def agent
         @agent ||= agent_class.new.tap do |agent|
           agent.params = @params
+          agent.current_user = @actor
           agent.process(action_name, *args, **kwargs)
         end
       end
@@ -180,8 +213,12 @@ module ActiveAgent
         if processed?
           super
         else
+          # The actor rides as an ordinary job argument, which ActiveJob
+          # serializes through GlobalID like any other record, so a worker on
+          # another machine authorizes as the same caller.
           agent_class.generation_job.set(job_options).perform_later(
-            agent_class.name, action_name.to_s, generation_method.to_s, params: @params, args: args, kwargs: kwargs
+            agent_class.name, action_name.to_s, generation_method.to_s,
+            params: @params, args: args, kwargs: kwargs, actor: @actor
           )
         end
       end