Repository navigation
Conversation
Codecov Report❌ Patch coverage is Additional details and impacted files@@ Coverage Diff @@
## develop #961 +/- ##
=============================================
+ Coverage 75.55% 75.60% +0.05%
- Complexity 3381 3562 +181
=============================================
Files 138 145 +7
Lines 13081 13606 +525
=============================================
+ Hits 9883 10287 +404
- Misses 3198 3319 +121
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
✅ WordPress Plugin Check Report
📊 ReportAll checks passed! No errors or warnings found. 🤖 Generated by WordPress Plugin Check Action • Learn more about Plugin Check |
There was a problem hiding this comment.
Pull request overview
Adds experimental dedicated WordPress accounts for external AI agents.
Changes:
- Provisions agent accounts with Application Passwords and restricted capabilities.
- Adds admin, Users screen, and REST identity surfaces.
- Adds documentation and integration tests.
Reviewed changes
Copilot reviewed 8 out of 8 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
includes/Experiments/Experiments.php |
Registers the experiment. |
includes/Experiments/Agent_Users/Agent_Users.php |
Initializes agent-user services. |
includes/Experiments/Agent_Users/Agent_Account.php |
Implements provisioning and identity restrictions. |
includes/Experiments/Agent_Users/Admin_Page.php |
Adds provisioning and listing UI. |
includes/Experiments/Agent_Users/Users_Screen.php |
Adds agent filtering and badges. |
includes/Experiments/Agent_Users/REST_Field.php |
Exposes the agent marker through REST. |
includes/Experiments/Agent_Users/README.md |
Documents behavior and limitations. |
tests/Integration/Includes/Experiments/Agent_Users/Agent_UsersTest.php |
Tests core agent-account behavior. |
Suppressed comments (2)
includes/Experiments/Agent_Users/Admin_Page.php:383
- The result key is shared by every provisioning request from the same administrator. If two tabs submit before either redirect is rendered, the second result overwrites the first; one newly created agent's only plaintext credential is then never shown, and a redirect may display the other request's result. Correlate each redirect with a unique, unguessable one-time result identifier (or avoid the shared PRG storage entirely).
private function store_result( array $result ): void {
set_transient( self::RESULT_TRANSIENT_PREFIX . get_current_user_id(), $result, 5 * MINUTE_IN_SECONDS );
includes/Experiments/Agent_Users/Admin_Page.php:383
- This transient contains the plaintext Application Password from the success result. On a standard WordPress install,
set_transient()serializes it intowp_options(or sends it to the external object cache), contradicting the stated one-time, never-stored credential model and exposing a live secret to database/cache readers and transient hooks. Return the credential through a non-persistent one-time response such as core's Application Password flow, or protect it with an appropriately encrypted one-time channel.
private function store_result( array $result ): void {
set_transient( self::RESULT_TRANSIENT_PREFIX . get_current_user_id(), $result, 5 * MINUTE_IN_SECONDS );
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
600b7af to
d822ecc
Compare
|
The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message. To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook. |
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 11 out of 11 changed files in this pull request and generated 1 comment.
Suppressed comments (4)
includes/Experiments/Agent_Users/Agent_Account.php:297
map_meta_cap()is user-specific and filterable, sodo_not_allowhere does not prove that nobody can hold this capability. A plugin may deny a capability only to the provisioner but allow it for the new agent; skipping the subsequentcurrent_user_can()check then permits exactly the escalation this method is meant to prevent. Only special-case capabilities known to be globally unavailable, rather than everydo_not_allowresult.
// Skip capabilities nobody can hold on this site, such as `manage_links` without the Link Manager.
// phpcs:ignore WordPress.WP.Capabilities.Undetermined -- Mapping every capability granted by the selected role.
if ( in_array( 'do_not_allow', map_meta_cap( $capability, $current_user_id ), true ) ) {
continue;
includes/Experiments/Agent_Users/Agent_Account.php:132
- Provisioning does not require permission to edit the created user. The integration test's limited manager has
create_usersandpromote_usersbut noedit_users, so it can create an agent, yetget_edit_user_link()returns no usable profile URL and core's Application Password endpoint denies managing that agent. Require the relevant edit permission or handle this supported role without redirecting it to an inaccessible credential screen.
public static function current_user_can_provision(): bool {
return current_user_can( 'create_users' ) && current_user_can( 'promote_users' );
includes/Experiments/Agent_Users/New_User_Screen.php:349
- The second
wp_die()argument is the page title, not the HTTP status. This renders403as the title while the response keeps the default error status. Pass the response code through the$argsparameter so unauthorized submissions actually return HTTP 403.
wp_die( esc_html__( 'Sorry, you are not allowed to create agent accounts.', 'ai' ), 403 );
includes/Experiments/Agent_Users/README.md:26
- This contradicts the bootstrap implementation:
Main::load()registersAgent_Accountsafeguards beforeRequirements::are_requirements_met()evaluateswp_supports_ai(). When AI support is disabled, provisioning/UI do not load, but login, reset, and capability safeguards still run. Document that distinction so operators do not assume the agent restrictions disappeared.
1. WordPress core reports AI support via `wp_supports_ai()`. When the environment disables AI, the plugin does not load at all, so none of this code runs.
jorgefilipecosta
left a comment
There was a problem hiding this comment.
From the code/technical point of view this seems to be on a very good direction. I think multisite presents a whole set of challenges and we are not handling things to deal with multisite yet, It is probably better to disable this experiment on multisite and then have a follow up PR focused on multisite.
In terms of UX, we are forcing agents to have an email, I think email could be optional defaulting to the agent creator email, or even have the email field prefielled with the original author email. It may be tricky if emails are unique per user if that's the case I think it should be ok for agent users to not have an email.
|
Thank you for the review, @jorgefilipecosta! Agreed on multisite. It brings its own set of questions, like the network Users screen, the network profile screen, and the fact that user meta is shared across the whole network. I will keep this PR focused on the general mechanism and handle multisite in a dedicated follow-up PR. To avoid a half-working state, this PR will disable the experiment when multisite is detected. The safeguards for existing agent accounts stay active either way. On the email, it has to stay unique. WordPress enforces that in One idea for a follow-up: offer a button to fill or simply prefill the field with a plus-addressed suggestion based on the creator's email, for example |
|
I changed direction from disabling the experiment on multisite to supporting site-bound agents in this PR. Each agent records the site where it was created and can authenticate only while it remains a member of that site. Roles on other sites do not expand access. Agents cannot be added elsewhere or become super admins, and site administrators can manage only agents assigned to their site. This is implemented and covered by multisite tests in a521681. |
|
Summary of the latest changes after review:
|
|
All this sounds fantastic!
I am not sure this is necessary and breaks some of the WordPress logic. One thing that I like in telegram is that when you are creating a telegram bo, the login has to end with The other thing is that Linear makes it super explicit when something was done by the agent and on behalf of whom - I think this would be neat.
|
|
Thanks @artpi, all good points! You are right about multisite. I picked the strict site binding because I did not know this area well enough. After checking core again, site roles already give the boundary we need. Only super admins can create an active user without email confirmation, and adding an existing user to another site sends an invitation that the agent's email owner has to confirm. So I will remove the site binding and treat agents as regular network users. Roles decide where an agent can act, and core decides who can manage the account. The only extra rule that stays is that an agent cannot become a super admin. I like the On "acting on behalf": as I noted earlier, I would keep two cases separate for now. Agent accounts always act on their own behalf, with their own role and attribution. That is what this PR covers. The person who creates the agent is only its creator, not the one the agent acts for. The other case is a human account used by an external agent. There the work belongs to the person, and we would mark it as agent assisted. That needs a different attribution model and fits better with the audit trail work. |
Compatibility note: agent users and code that assumes a principal is humanFollowing up on my #961 test with the compatibility note I offered. These are the ecosystem-side seams I have hit or reproduced where "an agent is a normal, queryable WordPress user" meets code that quietly assumed a principal was a person. None are defects in the experiment; they are the adjustments the surrounding code needs once agent users exist. I found all of these against real sites, most of them the hard way before agent users existed. 1. Resolving a principal by role can now resolve to an agentAny code that answers "who should I act as" by querying for a role will, on some sites, get an agent. The canonical shape: get_users( array( 'role' => 'administrator', 'number' => 1, 'orderby' => 'ID', 'order' => 'ASC' ) );Reproduced against #961: with an Administrator agent whose ID is lower than any human administrator (original admin deleted or renamed, or the site provisioned agent-first via WP-CLI or a host), this returns the agent, and the caller adopts it as the content-owning principal. This is correct behaviour from the experiment (agents must stay queryable so ownership and capability code keeps working). The fix belongs in the resolver: exclude agents when picking a principal to act as. // Before
get_users( array( 'role' => 'administrator', 'number' => 1, 'orderby' => 'ID', 'order' => 'ASC' ) );
// After: a human principal, not another agent
get_users( array(
'role' => 'administrator',
'number' => 1,
'orderby' => 'ID',
'order' => 'ASC',
'meta_query' => array( array( 'key' => 'wpai_agent', 'compare' => 'NOT EXISTS' ) ),
) );A stable 2. Role-based user queries already miss admins; agents widen the blast radiusTwo failures I shipped before agent users existed, both caused by a principal the query could not see. They matter here because agent users are one more principal these queries mishandle, and any resolver touched by note 1 above should account for both.
The guidance worth stating out loud for anyone touching user queries: hiding an agent is a display concern (author dropdowns, participant lists), never a query concern. Normal queries must keep returning agents; only the UI should omit them. 3. A single-site Editor agent carries
|
|
One finding while adding the |
|
Thanks @webmyc for testing and for the detailed notes! On The points about role queries need further investigation. Some of the reported cases look like expected WordPress behavior. An agent is a regular user with a role, so a query for that role will return it, and a super admin who is not a member of a site does not show up in that site's user list. |
|
@gziolo on the Administrator-agent case is not the interesting one. an admin agent is fully trusted, can install plugins, and reasoning about one capability there is deck-chair arrangement, agreed. the interesting tier is below admin, because the whole promise of this proposal, in your words on #923, is a principal smaller than an administrator that can still own content. Editor is the natural role for that principal, and on single-site Editor ships the "blocks legitimate cases" concern is real, my fleet is the evidence: agents legitimately write builder markup, embeds, styles all day. but i have run both sides of this tradeoff in production, and the answer that worked is not a binary cap. it is: safe default, plus a site-owned escape hatch that is narrower than on the role queries, no disagreement: both behaviors are core semantics working as designed, which is what the note says too. i included them as integrator context, not as bugs, because the resolver-adoption case is code that exists in the wild today (mine included) and will misfire the day agent users ship. if it is useful, i am happy to reshape that section into a short "guidance for integrators" block for the experiment README: resolvers that pick a principal to act as should consult the |
87be0bd to
cf5555f
Compare
|
@artpi @webmyc thank you, both rounds of feedback are now in the branch:
Two things I decided to postpone:
|
Brings in the Agent Users experiment exactly as proposed in WordPress#961 (head dcae15b), rebased onto develop, so the parent/child changes that follow can be reviewed as separate commits. Co-authored-by: Greg Ziółkowski <grzegorz@gziolo.pl>
|
I opened #1068 which builds on this PR to explore the "subuser" idea for these agent users. |
|
@jeffpaul, I’ve updated the description to link to #211 and acknowledge @Jameswlepage’s prior work. I’ll also compare the approaches to see whether I missed anything important, and make sure James is credited when this is merged. @nerrad, thank you for opening #1068 to make your suggestion more concrete. Am I understanding correctly that you see every agent account as acting on behalf of a specific human account, with that relationship being mandatory? My initial thinking was to record who created the agent, but I hadn’t settled on how much that relationship should govern its behavior afterward. For example, on a site with multiple administrators, I imagined a shared agent account that authorized administrators could manage and use, with permissions defined by the agent’s own role. Your proposal makes the parent relationship central: the agent’s permissions remain bounded by the parent’s current permissions, and its lifecycle is tied to that account. I can see the benefits for managing delegated access and attributing work as performed on someone’s behalf. Although, if multiple people use the same agent credentials, the parent relationship alone wouldn’t identify who initiated a particular action. Do you think we should support both agents acting for an individual and shared agents managed at the site level, or should every agent require a human parent? I think clarifying that would help us decide whether parent ownership is fundamental to the identity model or an additional relationship we support. |
By default, yes. I think an important part of trust boundaries and audit trails is knowing who an agent acts on behalf of and any changes to that users authorization/capabilities should in turn apply to any agent(s) attached to them (which my PR does in a limited sense, would still need some work). It gives site owners the ability to allow users to have agents act on their behalf on the site, while still controlling access and privileges primarily through the human user.
I get the utility, but the audit trail for who directs the agent is less clear. If sites really wanted to operate with that model, they still could with my proposed approach, they'd just have to be more intentional about it (it's also why I left inline comments in my PR about addtional filters that could be added). Also, have you thought through multi-site behaviour with the unattached agent model?
Sure, but that's an intentional choice by site owners to accept that dilution of the controls. Agent delegation has not removed that choice. It's the same in that case as if people share one login account.
I think we should start with every agent requiring a human parent. With the right extensibility around things like labelling, site owners could still use a shared credentials approach (for example create a "bot user" as the parent, and all agents are children of that user), but out of the gate we ship with a more secure, auditable, trust model. That gives space to evaluate the necessity for a standalone agent actor/user. |
|
Could agents get a default avatar? Without a Gravatar, an agent gets the site default, so Presence API's admin bar shows a mystery person beside its Agent badge. A |
Using the flask/beaker icon would be a nice touch |
|
One data point from production for @nerrad's sub-user idea in #1068, since it is the model Respira ships today: a connection is approved by a logged-in person in the browser, and the token is bound to that person and to the one site they approved. Revoking the person's access ends the agent's. In practice agencies ask "which human let this agent in" more often than "which agent did this", so I lean toward the agent being tied to a parent by default, with the shared agent account @gziolo describes as the opt-in exception rather than the rule. |
|
@webmyc, thank you for confirming that the proposal from @nerrad would be the preferred approach. I'm inclined to close this PR in favor of #1068 (@nerrad most likely can't push to this PR), as it builds on this work while ironing out a few important details around the parent user idea. @josephfusco, great idea to change the default avatar. Let's ensure it gets integrated 👍🏻 |
WordPress#961 was closed in favor of this branch and never shipped, so no agents exist from before the parent link. Describe parentless agents and the multisite exception without pointing at it.
Brings in the Agent Users experiment exactly as proposed in WordPress#961 (head dcae15b), rebased onto develop, so the parent/child changes that follow can be reviewed as separate commits. Co-authored-by: Greg Ziółkowski <grzegorz@gziolo.pl>
WordPress#961 was closed in favor of this branch and never shipped, so no agents exist from before the parent link. Describe parentless agents and the multisite exception without pointing at it.
Brings in the Agent Users experiment exactly as proposed in WordPress#961 (head dcae15b), rebased onto develop, so the parent/child changes that follow can be reviewed as separate commits. Co-authored-by: Greg Ziółkowski <grzegorz@gziolo.pl>
WordPress#961 was closed in favor of this branch and never shipped, so no agents exist from before the parent link. Describe parentless agents and the multisite exception without pointing at it.
Gives external software a dedicated WordPress user, marked as an agent and linked to a human parent it acts on behalf of (WordPress#923). An agent: - authenticates only with Application Passwords: password login, resets, and password changes are blocked, and its password stays unknown; - can never do more than its parent currently can, since every capability check is repeated for the parent after all other mapping; - cannot hold a role that manages the site, change other users, or write unfiltered HTML; - shares post ownership with its parent; - is suspended, keeping its account and content, wherever its parent is missing, cannot have agents (`wpai_add_agents`), or is not a member. Agent_Account answers who is an agent, who its parent is, and whether it is suspended. Agent_Provisioner creates agents after checking the provisioner, the parent, and that the role grants nothing either lacks. Agent_Authentication and Agent_Capabilities enforce the rules, and Main registers them whenever the plugin is active, independent of feature toggles, since agent accounts outlive them. On multisite, provisioning requires network activation, because the agent marker is network-wide. Builds on the Agent Users experiment from WordPress#961. Co-authored-by: Greg Ziółkowski <grzegorz@gziolo.pl>
Registers the Agent Users experiment, which loads provisioning and presentation only while it and the AI features are enabled. Agent management stays on core's user screens, because an agent is a user: - Users → Add Agent reuses the Add User form, with a required parent field and without password or notification controls, then opens the agent's profile to create its first Application Password; - the agent profile hides human-only settings and explains why an agent is suspended, and human profiles list their agents; - the Users list labels agent roles with their parent, filters by account type, and swaps the password reset action for credentials; - REST user responses expose read-only `wpai_is_agent` and `wpai_agent_parent` fields, for "agent on behalf of" bylines; - agents fall back to the plugin's flask avatar. On multisite without network activation, the Add Agent screen is unavailable and the user screens explain why. Builds on the Agent Users experiment from WordPress#961. Co-authored-by: Greg Ziółkowski <grzegorz@gziolo.pl>
Gives external software a dedicated WordPress user, marked as an agent and linked to a human parent it acts on behalf of (WordPress#923). An agent: - authenticates only with Application Passwords: password login, resets, and password changes are blocked, and its password stays unknown; - can never do more than its parent currently can, since every capability check is repeated for the parent after all other mapping; - cannot hold a role that manages the site, change other users, or write unfiltered HTML; - shares post ownership with its parent; - is suspended, keeping its account and content, wherever its parent is missing, cannot have agents (`wpai_add_agents`), or is not a member. Agent_Account answers who is an agent, who its parent is, and whether it is suspended. Agent_Provisioner creates agents after checking the provisioner, the parent, and that the role grants nothing either lacks. Agent_Authentication and Agent_Capabilities enforce the rules, and Main registers them whenever the plugin is active, independent of feature toggles, since agent accounts outlive them. On multisite, provisioning requires network activation, because the agent marker is network-wide. Builds on the Agent Users experiment from WordPress#961. Co-authored-by: Greg Ziółkowski <grzegorz@gziolo.pl>
Registers the Agent Users experiment, which loads provisioning and presentation only while it and the AI features are enabled. Agent management stays on core's user screens, because an agent is a user: - Users → Add Agent reuses the Add User form, with a required parent field and without password or notification controls, then opens the agent's profile to create its first Application Password; - the agent profile hides human-only settings and explains why an agent is suspended, and human profiles list their agents; - the Users list labels agent roles with their parent, filters by account type, and swaps the password reset action for credentials; - REST user responses expose read-only `wpai_is_agent` and `wpai_agent_parent` fields, for "agent on behalf of" bylines; - agents fall back to the plugin's flask avatar. On multisite without network activation, the Add Agent screen is unavailable and the user screens explain why. Builds on the Agent Users experiment from WordPress#961. Co-authored-by: Greg Ziółkowski <grzegorz@gziolo.pl>
📢 Work continues in #1068.
What?
See #923.
Supersedes #211 by @Jameswlepage.
This PR adds the experimental Agent Users feature. It gives external software—AI agents, MCP clients, scheduled jobs, and similar tools—dedicated WordPress identities instead of requiring them to borrow a human account.
This PR covers the identity model. Richer audit trails and provenance can build on that identity separately.
Why?
An external agent currently has two poor identity choices: reuse a human credential, which mixes attribution and revocation, or run without a user, which loses authorship and produces surprising capability behavior.
An agent account reuses WordPress's existing user primitive. Roles, content ownership, revisions, comments, deletion with reassignment, and user-based logs therefore continue to work. The agent's access can be changed or revoked without modifying a human account.
How?
An agent is a regular WordPress user marked by
wpai_agentuser meta. The agent acts as its own principal: the creator is recorded as provenance inwpai_agent_created_by, not as the person the agent acts for. The marker changes the account's identity and authentication contract while preserving core user behavior:Editor (agent), provides account-type filtering, and replaces password reset with an Application Passwords shortcut._agent. Provisioning appends the suffix when it is missing, including for programmatic callers. That makes agents easy to spot wherever only the login is shown, such as WP-CLI output, author names, and logs.unfiltered_html, most notably Editor on single site, and model output stored with it becomes stored XSS (scripts saved into content). The capability is stripped from every agent withoutmanage_options, so their content passes core's normal KSES filtering. The check matches the resolved primitive, which also covers meta capabilities such asedit_css.create_users,promote_users, and the primitiveedit_userscapability needed to manage the resulting account. The selected role must be within the provisioner's effective capabilities. That comparison runs first while listing roles and again against the real marked agent after creation, so user-specific capability filters cannot give the agent a role capability denied to its provisioner. A failed final check rolls the account back before core'sedit_user_created_usercompatibility and notification action runs. Capabilities that are inert for the agent, such as the strippedunfiltered_html, do not count against the provisioner.wpai_is_agentfield, and the globalwpai_is_agent_user()helper gives plugins one documented way to detect agent accounts.Multisite model
WordPress stores user identity and Application Passwords across the network, while site memberships and roles are site-specific. Agent accounts follow that core model instead of adding a parallel boundary:
manage_network_userscapability edit other users on multisite. The same rule decides who can provision agents and manage their credentials.The plugin must be network-activated when this experiment is used on multisite. The agent marker is network-wide, so every site has to enforce the login and password-reset safeguards.
Core hardcodes several user-screen labels and action positions. Small inline scripts progressively enhance those labels for agents; without JavaScript, the underlying core forms continue to work.
Out of scope: assistants running inside a logged-in human session, credential protocols such as OAuth and expiry, per-run audit correlation, trust tiers, and approval workflows.
Use of AI Tools
Testing Instructions
Application Passwords require HTTPS or
WP_ENVIRONMENT_TYPEset tolocal. With wp-env, add a git-ignored.wp-env.override.jsoncontaining{"config": {"WP_ENVIRONMENT_TYPE": "local"}}and restart.Single site
_agent.curl -u 'USERNAME:PASSWORD' 'https://your-site/wp-json/wp/v2/users/me'.<script>tag and confirm KSES strips it. A human Editor keeps core's single-site behavior.Multisite
Run the focused suites:
npm run test:php -- --filter Agent_UsersTest npx wp-env --config=.wp-env.test.json run cli --env-cwd=wp-content/plugins/ai bash -c "WP_MULTISITE=1 vendor/bin/phpunit -c phpunit.xml.dist --filter Agent_UsersTest"Screenshots or screencast
Users screen with the Add Agent action, the
(agent)marker, and the account-type filter:Users → Add Agent, using core's Add User form in agent mode:
An agent profile with the account note and human-only sections hidden:
Changelog Entry