Repository navigation
Conversation
Codecov Report❌ Patch coverage is Additional details and impacted files@@ Coverage Diff @@
## develop #1068 +/- ##
=============================================
- Coverage 84.31% 83.34% -0.98%
- Complexity 3744 4291 +547
=============================================
Files 149 161 +12
Lines 14170 15632 +1462
=============================================
+ Hits 11948 13029 +1081
- Misses 2222 2603 +381
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:
|
29b53b4 to
49070ed
Compare
|
The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. Unlinked AccountsThe following contributors have not linked their GitHub and WordPress.org accounts: @chubes4, @nikolas4175-godaddy. Contributors, please read how to link your accounts to ensure your work is properly credited in WordPress releases. 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. Props Bot commandsYou can trigger Props Bot actions by commenting on this PR:
|
|
@nerrad note that I'm holding off on pinging folks for review as this shows as in draft, so please open this up for review when you're ready, thanks! |
|
Yup I moved out of draft prematurely by mistake and then moved it back because i wanted it to be a reference for discussion on #961 first. If we're good with trying this approach this PR would likely supersede 961. |
|
@nerrad, based on the conversations, I closed #961 in favor of this enhanced approach. Let's continue the development here. I plan to review and test the changes applied this week. Additionally, I want to ensure that the #961 (comment) from @josephfusco doesn't get lost in the process:
|
|
I would like to summarize the feedback from #923 and agree on what we need before merging this as an experiment. The implementation already covers much of what we need. I would focus on these four points:
I would leave controls for individual abilities, a broader permission model based on risk, agent creation by parents, and additional customization hooks for later work. I will use these points to guide my review and testing. We can then identify which changes are required before merging and which can follow after we gather feedback from the experiment. |
gziolo
left a comment
There was a problem hiding this comment.
Three findings from testing the permission and deletion behavior.
|
I was thinking about E2E testing scenarios that could also serve as acceptance criteria for this experiment. These would complement the PHP tests by checking browser flows and making real REST requests with the agent’s credentials. Five scenarios seem useful:
These tests would check that the flows work together. A manual walkthrough would still help us check whether the explanations are clear to someone using the feature for the first time. |
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>
…them The agent safeguards are plugin code, so while the plugin is inactive nothing limits an agent to its parent or rejects its Application Passwords. Deactivating the plugin on purpose therefore revokes them, network-wide on network deactivation, and the Plugins screen confirms first while agents exist. Core updates plugins without running deactivation hooks, so updating leaves credentials alone. Activation revokes any agent credential that exists at that point, since the plugin never bounded it, and tells each parent once, by email and in an admin notice, which agents need a new Application Password. An agent presenting a revoked credential gets `wpai_agent_credentials_revoked` naming that parent, and a suspended one `wpai_agent_suspended`, instead of core's generic `rest_not_logged_in`. Only a credential that was real gets either, so the errors do not reveal which accounts are agents.
An agent acts for its parent, so it follows the parent's account: - deleting the parent deletes their agents, and agent content is reassigned to the same user as the parent's, or otherwise treated exactly as core treats the parent's; the delete screens count agent content, name the agents that go too, and never offer them as heirs; - on multisite, removing the parent from a site removes their agents from it, deleting the parent from the network deletes their agents, and the network delete screen adds core's delete-or-reassign choice for agent content on sites the parent does not belong to; - an agent can only join sites its parent belongs to, or any site under a super admin parent, and can never become a super admin. Agent_Lifecycle holds these rules, and Main registers them with the other agent safeguards.
The authentication and capability rules filter every capability check, so installs that never create an agent should not pay for them. The `wpai_agents_exist` network option records whether an agent may exist: activation computes it, a missing value is computed on the next request, and marking any account as an agent sets it and registers the rules for the rest of that request. While it says no agent exists, whoever authenticates, by password, Application Password, or session, or asks for a password reset is checked, so an agent marked behind the plugin's back, such as with WP-CLI's `--skip-plugins`, or on another network of a multi-network install, still gets the rules before it can act. Since registration can now happen late, from any of those hooks, Main checks what is already registered so the rules never register twice. Who may have agents and the account lifecycle rules always run, since they are needed before the first agent exists and only run on rare events.
Covers the Agent Users flows in a browser: creating an agent and its first Application Password, a parent managing their agent's credentials, agent access following the parent's permissions, deleting a parent with content reassignment, and deactivation revoking credentials with reactivation explaining how to reissue them. On a multisite network, it covers the Add Agent form, removing a parent from one site, and the network delete screen's choices for agent content on sites the parent does not belong to. Adds a multisite wp-env configuration and Playwright config, the `test:e2e:multisite` and `wp-env:test-multisite` scripts, and a CI job running the multisite specs, which the "Run E2E tests" check now waits for. The E2E helper plugin gains endpoints for the multisite setup.
319ce2d to
770c480
Compare
|
|
||
| $own_counterparts = array( | ||
| $post_type->cap->edit_others_posts => $was_published ? $post_type->cap->edit_published_posts : $post_type->cap->edit_posts, | ||
| $post_type->cap->edit_private_posts => $post_type->cap->edit_posts, |
There was a problem hiding this comment.
Re-posting @gziolo's thread from before the force-push:
An Author agent cannot edit its own private post because the parent check still requires
edit_private_posts. Could we fix the mapping and add a test for private posts?"
Fixed. For posts an agent and its parent share, share_post_ownership() swaps the private-post capabilities for their own-post counterparts (this line and the two below), so the parent is checked under its own-post rules too. test_shared_ownership_covers_private_posts covers it, and test_linking_leaves_access_to_others_posts_unchanged checks that linking grants nothing over anyone else's posts.
|
|
||
| // Like core for the author, a trashed post that was published still counts as published. | ||
| $was_published = 'trash' === $post->post_status && | ||
| in_array( get_post_meta( $post->ID, '_wp_trash_meta_status', true ), array( 'publish', 'future' ), true ); |
There was a problem hiding this comment.
Re-posting @gziolo's thread from before the force-push:
A Contributor parent can permanently delete an agent's trashed post that was previously published, although they cannot do this with their own post. Could we preserve the check for the previous post status and add a test?
Fixed. A trashed post whose _wp_trash_meta_status was publish or future keeps requiring the published-post capabilities, as core maps the author's own post. test_shared_ownership_keeps_own_post_limits covers it.
| * @param array<int, array{agent: \WP_User, parent_id: int}> $agents Agents being deleted, keyed by ID. | ||
| * @param array<int, int> $excluded Users being deleted, who cannot receive content. | ||
| */ | ||
| private function render_agent_content_on_other_sites( array $agents, array $excluded ): void { |
There was a problem hiding this comment.
Re-posting @gziolo's thread from before the force-push:
Deleting a parent also trashes agent posts on sites the parent does not belong to. Those sites are missing from the confirmation and reassignment options. We should address this before merging, so users do not lose content unexpectedly. What would be the best way to handle this?
What changed:
- Agents can now only join sites their parent belongs to, or any site under a super admin parent (
keep_agents_on_parent_sites()), so this case is now rare. - Where it still happens (a super admin parent who isn't a member, or content attributed to the agent directly), the network delete screen adds core's delete-or-reassign choice for the agent on each of those sites (this method). Archived and spam sites are included.
- Agent content on the parent's own sites follows the parent's choice exactly as core applies it to the parent. The plugin no longer deletes agent content itself. One consequence: "Delete all content" during a network delete leaves the agent's posts behind, just as core leaves the parent's. That's core behavior for every user, and probably worth a Trac ticket.
- On WP 7.0, whose network delete screen still lists the deleted users' agents as heirs, choosing one, or reassigning with nobody left to receive the content, is rejected before anything is deleted (
reject_agents_as_network_heirs()).
Covered by test_multisite_delete_screen_offers_agent_content_on_other_sites, test_multisite_agent_content_without_receiver_is_deleted_with_agent, test_multisite_parent_delete_choice_treats_agent_content_like_the_parents, test_multisite_network_deletion_rejects_agents_of_deleted_users_as_heirs, and test_multisite_archived_sites_still_belong_to_parent_and_agent, plus the multisite E2E spec.
| * | ||
| * @param bool $network_wide Whether the plugin is being deactivated across the network. | ||
| */ | ||
| public static function revoke_on_deactivation( bool $network_wide ): void { |
There was a problem hiding this comment.
Re-posting @gziolo's thread from before the force-push (it was on Main.php):
These safeguards only run while the plugin is active. After deactivation, agents keep their full role without the parent limit, suspended agents can authenticate again, and Editor agents get
unfiltered_htmlback. [...] Could we warn about it before deactivation when agents exist, and document it in the README?
I decided to go further than the warning:
- Deactivating the plugin on purpose revokes every agent's Application Passwords (network-wide on network deactivation). The Plugins screen warns, and the Deactivate link asks for confirmation while agents exist. Core updates plugins without running deactivation hooks, so updates leave credentials alone.
- Activation revokes any agent credential that exists at that point, since the plugin never bounded it (unless an update left the plugin inactive), and tells each parent once, by email and with an admin notice, which agents need a new Application Password.
- An agent presenting a revoked credential gets
wpai_agent_credentials_revoked, naming the parent who can issue a new one. - Agents never have a usable password: provisioning sets a random one, and profile, REST,
wp_update_user(), andwp_set_password()updates keep it. A reset by email still works while the plugin is inactive; the README says so. - On multisite with only per-site activation, nobody can create new agent credentials, because one would authenticate on sites where nothing bounds it.
The README's "Enablement and retirement" section documents all of this.
| } | ||
|
|
||
| if ( is_multisite() && ! self::belongs_to_site( $parent->ID, get_current_blog_id() ) && ! is_super_admin( $parent->ID ) ) { | ||
| return 'parent_not_member'; |
There was a problem hiding this comment.
Re-posting @gziolo's thread from before the force-push:
On multisite, this checks the parent on the current site. If the parent is not a member there and is not a super admin, the agent counts as suspended on that site. Its Application Password is then rejected, and the Users screen says the parent 'can no longer have agents', which is not the real reason. [...] Which behavior do we want? The multisite test only covers a super admin parent, so a test with a regular parent would help too.
I decided to keep suspension and made it the backstop. Agents can only join sites their parent belongs to (Agent_Lifecycle::keep_agents_on_parent_sites()), and where an agent ends up on another site anyway, for example through WP-CLI, it's suspended there with its own reason, parent_not_member. The REST error and the profile now name that reason, the Users list marks the agent as suspended instead of blaming the parent's eligibility, and the network profile lists the sites where the agent is suspended. The README describes per-site suspension. With a regular parent: test_multisite_agent_is_suspended_where_parent_is_not_a_member and test_multisite_agent_joins_only_sites_of_its_parent.
| * | ||
| * @param bool $network_wide Whether the plugin is being activated across the network. | ||
| */ | ||
| public static function on_activation( bool $network_wide ): void { |
There was a problem hiding this comment.
Highlighting for reviewers that deliberate activation revokes every agent credential that exists at that point, since the plugin never bounded it, unless a marker set while updating (note_update() / forget_update()) says an update left the plugin inactive. A missing marker revokes credentials that were fine and sends a reissue email: disruptive, but safe. A stale marker is the risky direction: it would skip revoking credentials created while the plugin was inactive. How the marker is set and cleared deserves scrutiny.
| * @param int|string $user_id Deleted user ID. | ||
| * @param int|null $reassign User ID receiving the deleted user's content, or null. | ||
| */ | ||
| public function delete_agents_of_deleted_user( $user_id, $reassign ): void { |
There was a problem hiding this comment.
Highlighting for reviewers that deleting a parent deletes their agent accounts, and the agents' content follows the parent's reassignment choice. This is the one place the plugin deletes accounts by itself, so a wrong parent link here means a deleted account. The links are protected from capability-checked meta writes (auth_user_meta_*), and agents can never be parents.
| * | ||
| * @since x.x.x | ||
| */ | ||
| public function reject_agents_as_network_heirs(): void { |
There was a problem hiding this comment.
Highlighting for reviewers that on network users.php with action=dodelete, this runs on load-users.php, before core's per-site loop, and stops the request if a deleted user's own agent was picked as heir, or if a "reassign" has nobody to receive the content. It depends on that hook order and on the request shape of WP 7.0's and 7.1's network delete screens, which differ. No test pins the hook order; the integration tests call the method directly. This should get scrutiny.
| add_action( 'added_user_meta', array( $this, 'register_safeguards_for_marked_agent' ), 10, 3 ); | ||
| add_action( 'updated_user_meta', array( $this, 'register_safeguards_for_marked_agent' ), 10, 3 ); | ||
|
|
||
| if ( ! Agent_Account::agents_may_exist() ) { |
There was a problem hiding this comment.
Highlighting for reviewers that the per-request safeguards register only once wpai_agents_exist says an agent may exist. The risk is the flag reading 0 while an agent exists. It's set whenever any account is marked as an agent, computed when missing, and recomputed on activation. Until it flips, whoever authenticates (by password, Application Password, or session) or requests a password reset is checked first, at priority 0, so an agent marked behind the plugin's back gets the safeguards before it can act. Who may be a parent and the lifecycle rules always run.
The assumption is that agents_may_exist result is accurate. But I also think this needs scrutiny.
|
I meant to add this to the review body above but missed it I force-pushed this branch to hopefully help make it a bit easier to review. The history was about 80 commits (the #961 import plus review fixes); it's now six, each a batch that could be reviewed, and if we want, merged as its own PR (but we'd have to think about sequencing as noted below, so a release doesn't expose things it shouldn't):
Each commit passes PHPCS, PHPStan, and PHPUnit on single site and multisite by itself. 1 to 3 should land in the same release: until 3, deactivating the plugin leaves agent Application Passwords working without the parent limit.
The force-push detached the earlier inline threads. I re-posted each one where its code lives now, with what changed or what I propose, and added comments on the changes I'd most like a second pair of eyes on (I'll resolve the earlier threads so they don't clutter up the event stream in the PR). Open questions for maintainers:
|
|
note: I'm also working on updating the PR description so it more accurately represents the current state of the PR Done. |
| null !== $response || | ||
| 'GET' === $request->get_method() || | ||
| ! $request->has_param( 'password' ) || | ||
| 1 !== preg_match( '#^/wp/v2/users/(\d+|me)$#', $request->get_route(), $matches ) |
There was a problem hiding this comment.
Core matches routes in a case insensitive way, so this could be bypassed if someone requests something like .../Users/.
| $post_type->cap->edit_private_posts => $post_type->cap->edit_posts, | ||
| $post_type->cap->delete_others_posts => $was_published ? $post_type->cap->delete_published_posts : $post_type->cap->delete_posts, | ||
| $post_type->cap->delete_private_posts => $post_type->cap->delete_posts, | ||
| $post_type->cap->read_private_posts => $post_type->cap->read, |
There was a problem hiding this comment.
I think using cap values as keys will cause problems here. For example, nav menu editing is restricted to edit_theme_options and almost all the cap values are that. PHP will use the value of the last one, which might be read. In the wild, there could be any combination of cap values that cause this array to function in unexpected ways.
Builds the rest of the confirm half promised on WordPress#402. - Retries: a confirmation still runs its call once, and the response is kept until the confirmation would have expired. A retry of the same call (same token or state, user, tool and input) gets that response back. A retry that arrives mid-run waits briefly, then says the call is still running; it never runs twice. Protocol errors and results over 512 KB are not replayed. Only the response is stored. - Follow-ups: a confirmation may cover up to three follow-up calls, declared by the Ability (meta.mcp.confirmation_follow_ups) or a filter. Each is bound to one Ability and input for the same user and site, and is named in the question under "The same yes also covers". Anything else is asked as usual. - Approval link: clients with URL elicitation get a wp-admin page (admin-post.php) that the approver opens as themselves: the agent user's parent (wpai_get_agent_parent(), WordPress/ai#1068) or the calling person. Nonce-protected, only the approver can see or answer it, expires with the confirmation. Approving records channel "url" and approved_by; the client's retry then runs the call. - mcp_adapter_tool_call_confirmed now also carries the confirmation id, approved_by and follow_up_of, and fires once per confirmation. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The logging half of C4 in WordPress#402, stacked on the confirm branch. - One entry per confirmed call, as a private post type with no author: Ability, tool, input hash (never the input), the summary the person saw, channel, approver, the user and, for agent users from WordPress/ai#1068, its parent at the time (wpai_is_agent_user(), wpai_get_agent_parent()), the follow-up it was covered by, times and the result. Names are kept with the IDs, so entries survive deleting or reassigning users. - New action mcp_adapter_tool_call_confirmation_finished reports success, error or failed for each confirmed call. Replayed retries do not fire it again, so they are not logged twice. - Tools > Agent changes lists the entries: everything for users who can manage options, otherwise their own calls, their agents' calls and the calls they approved. - Keeps the newest 500 entries (filterable); can be turned off. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
@JasonTheAdams @dkotter even with the coming OAuth effort aligned to WP 7.3, I think its still worth getting this experiment into the AI plugin as a comparable option; any concerns with that? |
Yeah, I'd like to see this move forward. @nerrad There's a number of merge conflicts here that need cleaned up. Beyond those, anything else you're tracking before this is ready for review? I see there's a handful of open comments but not sure the status of those |
What?
Closes #923.
Adds the
Agent Usersexperiment: dedicated WordPress accounts linked to a human parent, with access bounded by that parent's current permissions.Supersedes #211 by @Jameswlepage and #961 by @gziolo. This PR builds on #961's code; its first two commits carry @gziolo as co-author. It implements the parent/child account suggestion.
@josephfusco requested a default agent avatar. @mathetos's testing and permission feedback on #923 informed the decision to keep agents out of site-managing roles. @gziolo summarized the acceptance criteria and E2E scenarios implemented by the end-to-end tests.
Why?
External agents need their own identities so their work is attributable and their credentials can be revoked independently of a human account. Linking each agent to a parent also prevents it from acting with more authority than the person it represents.
How?
How to review: The branch was force-pushed into six batches. Each can be reviewed and merged as its own PR, and each passes PHPCS, PHPStan, and PHPUnit on single site and multisite on its own. Batches 1–3 must ship in the same release: until batch 3, deactivating the plugin leaves agent Application Passwords working without the parent limit.
0e700110— Agent accounts and their security contract:Agent_Account,Agent_Provisioner,Agent_Authentication,Agent_Capabilities.4fb099e8— The experiment and its admin screens.52633e96— Revoking agent credentials when the plugin stops bounding them (Agent_Credentials).9b586d2a— Keeping agents with their parents as accounts come and go (Agent_Lifecycle).c072d5ea— Only running the per-request safeguards once an agent may exist.770c4804— End-to-end tests, including a multisite CI job.Inline review comments mark the spots most worth scrutiny.
Current behavior
WP_Usermarked bywpai_agentuser meta.wpai_agent_parentlinks it to a human parent;wpai_agent_created_byrecords the provisioner. The agent owns its work under its own account. Users → Add Agent requires an explicit eligible parent and appends_agentto the username.manage_optionsare unavailable to agents; agents cannot change other users or useunfiltered_html. Agent and parent treat each other's posts as their own under core's own-post rules.wpai_add_agentscontrols who may have agents, while user managers create them. Parents can edit their own agents' profiles and Application Passwords withoutedit_users; changing roles or deleting agents still uses core permissions.wpai_agent_suspended.wpai_agents_existnetwork option avoids registering per-request agent safeguards on installs without agents, while authentication and password-reset checks still detect an agent marked outside provisioning. Read-only REST user fieldswpai_is_agentandwpai_agent_parentappear inembed,view, andedit;wpai_is_agent_user()andwpai_get_agent_parent()expose the identity and link to PHP callers.See includes/Experiments/Agent_Users/README.md for the full design and behavior.
Deliberate choices
wp_userscolumn.Questions for maintainers
manage_network_users? This departs from core's model and has a@todoin code.wpai_agent_parent) stay public inviewandembed, or should the parent's display name also be exposed so public bylines always work?manage_options, such as installing plugins, or stay bounded by the parent?The experiment has not shipped, so there is no migration. Accounts marked as agents without a parent are suspended.
Use of AI Tools
Testing Instructions
npm run test:php -- --filter Agent_UsersTestandnpm run test:php:multisite -- --filter Agent_UsersTest.npm run test:e2e -- tests/e2e/specs/experiments/agent-users.spec.js tests/e2e/specs/experiments/agent-users-deactivation.spec.js. For multisite, startnpm run wp-env:test-multisite start, then runnpm run test:e2e:multisite.WP_ENVIRONMENT_TYPE=local.Agent Usersexperiment. Open Users → Add Agent. Confirm the parent is required and no role withmanage_optionsis listed.wpai_add_agentsto the parent with a role editor. Confirm the agent is marked suspended and its Application Password is rejected withwpai_agent_suspended.Screenshots or screencast
Users list: agents labeled with their parent, and a suspended agent.
Users → Add Agent: core's Add User form with a required parent.
Agent profile: the account note names the parent; human-only settings are hidden and Application Passwords stay.
A suspended agent's profile explains why.
A parent's profile lists their agents.
Deleting a parent names the agents deleted too, and counts agent content toward core's choice.
The Plugins screen warns that deactivating revokes agent credentials.
Changelog Entry