AI Agents framework, Phase A: synthetic users + user-meta definitions, abilities runner, chat

[epeicher]

What it does

Ships Phase A of the AI Agents framework: durable workers that live on the site as real WordPress users, take orders by chat, and act through the WordPress Abilities API under their own role and capabilities.

Behind the new agents extended option (OS Settings → Features → Extended options, admin-only, default off). With the flag on, a new Agents section appears in My WordPress: create an agent (name, role, description, system prompt), tick the abilities it may use in the Tools pane, configure triggers, and talk to it in the Agent chat window. Every tool call runs as the agent's own user and lands in the standard audit trail (revisions, comments, _edit_lock) attributed to the agent.

Rationale

This is the buildable slice of the direction #240 mocked, with one deliberate storage change: no wp_guideline CPT. An agent is split across exactly two layers:

• Identity: a synthetic wp_users row. Real role, real capability checks, real attribution. Every login path is blocked (authenticate filter, password resets, application passwords), the email is a never-delivered synthetic address, and the wp-admin Users list labels the row "Agent".
• Definition: user meta on that row (_desktop_mode_agent_*): description, instructions, ability allowlist, triggers, model override, rate limit.

Dropping the guideline CPT removes the Gutenberg Guidelines-experiment dependency entirely (no soft-gate, no 412 paths). The accepted trade-off is losing free revisions on prompt edits; instead, every mutation fires desktop_mode_agent_{created,updated,deleted} with before/after values per changed field, so logging plugins get a complete audit trail.

Implementation

Runner (includes/agents/runner.php): desktop_mode_agent_invoke() generates through the same Core AI Client adapter the Copilot uses (desktop_mode_ai_client_generate() over wp_ai_client_prompt()), loops function calls to a hard 8-turn cap, and dispatches each call via WP_Ability::execute() so the ability's own permission_callback and schemas gate it. The whole loop runs with wp_set_current_user() switched to the agent, restored in finally:

$previous_user_id = get_current_user_id();
wp_set_current_user( $user->ID );
try {
    $result = desktop_mode_agent_runner_loop( ... );
} finally {
    wp_set_current_user( $previous_user_id );
}

Tool schemas advertised to the model are projected through the Copilot's desktop_mode_ai_normalize_tool_schema() (providers 400 the whole request over one tool with a top-level oneOf/anyOf/allOf). Per-agent hourly rate limits ride a transient counter (default 60/hour, filterable). A desktop_mode_agent_runner_generate pre-filter short-circuits the AI Client, which is how PHPUnit exercises the full loop network-free.

Tools: the picker is a view over wp_get_abilities() with honest read-only vs mutating badges from meta.annotations.readonly. Unlike the Copilot (read-only only), agents may be granted mutating abilities; the compensating controls are the explicit allowlist set by an edit_users human plus the agent's role. Three new abilities ship: desktop-mode/get-post and desktop-mode/get-media (read-only) and desktop-mode/update-post (mutating, reachable only through an agent allowlist).

REST (/desktop-mode/v1/agents): CRUD + /invoke + abilities/trigger-kinds/hooks/roles catalogues. Reads and invokes default to edit_posts, writes to edit_users (all filterable); role assignment is constrained to a whitelist intersected with the acting user's get_editable_roles().

Client: an agent entity kind registered through the existing registerEntityKind() seam in the My WordPress bundle (list, Define/Tools/Triggers panes, create flow, live provider probe against /ai/status), plus a new lazy agent-run-window bundle for the chat window, fed through the cross-bundle desktop-mode/agents-chat shared store.

Triggers: chat is the only wired intake in Phase A. The other kinds (send-to, drag, hook, endpoint, agent) are declared in the trigger-kind catalogue so configuration can be stored now; their intakes land in later phases. All of them collapse to the same desktop_mode_agent_invoke() engine, and desktop_mode_agent_completed is the chaining seam.

First consumer — Remove Background extension (extensions/desktop-mode-remove-background/): a standalone plugin registering media-tools/remove-background, a mutating ability that removes an image's background and sideloads the result as a new PNG attachment authored by the agent. It touches zero desktop-mode internals — its whole integration surface is wp_register_ability() — which is the framework's compatibility claim demonstrated inside the PR. Backends are pluggable; the default is the WordPress AI Client (generative editing riding the site's Connectors credentials — no extension-specific key), with remove.bg and self-hosted rembg as opt-in mask-based alternatives. Configuration is deliberately code-level only (option, constants, or filter — no admin settings UI), so the ability is the extension's entire user-facing surface.

Testing instructions

npm run test:php -- --filter='Tests_DesktopMode_Agents'   # 45 tests
npm run test:js                                            # includes 20 agents tests

Manual, on a WP 7.0+ site with an AI connector configured:

1. OS Settings → Features → Extended options → tick Enable AI agents, reload.
2. My WordPress → Agents → create an agent (role author, prompt like "You audit posts"). Tick desktop-mode/get-post + desktop-mode/update-post in Tools.
3. Press Chat, ask "Fetch post 1 and tighten its title". Expect an answer with an expandable tool-call trace, and the post's revision attributed to the agent user.
4. Verify the blocks: the agent appears in wp-admin Users with the bot avatar and "Agent" type, logging in as it fails, and no application passwords can be created for it.
5. Without a connector, the section shows a warning notice pointing at Settings → Connectors and Chat is disabled; definitions remain editable.