Feature : Site Agent Experiment - #1214

What?

Closes #189

Adds an opt-in Site Agent experiment under Tools → Site Agent that maps natural-language requests to reviewed WordPress Abilities, with approval-gated writes and an audit trail.

Why?

Issue #189 asks for a conversational admin agent that can perform WordPress actions with strong security, permissions, and auditability from the start, and that is opt-in and disabled by default.

This PR takes an abilities-first approach. Instead of describing every action twice (once as a REST resource table, once as a custom action class), the agent uses ordinary WordPress Abilities as the action layer. Each action keeps its own input schema, permission callback, validation, and execution hook. The agent adds only three things:

1. A reviewed allowlist of abilities.
2. A propose-then-approve boundary for anything that is not read-only.
3. An audit trail.

This keeps the implementation substantially smaller than the earlier draft while preserving the security properties in the issue.

How?

Experiment and gates

• Site_Agent registers the screen, REST routes, abilities, and audit listener only when the experiment is enabled.
• The experiment toggle and the write gate both default to false.
• The screen and REST routes require manage_options by default; sites can narrow or lower this with wpai_site_agent_capability.

Abilities as actions

Read sections use their own capability (manage_options, edit_posts, edit_pages, activate_plugins) and filter object reads through read_post. The settings section never exposes URLs, email addresses, roles, or arbitrary options.

Proposal and approval flow

1. The model receives only the reviewed catalog.
2. An ability annotated readonly => true runs immediately.
3. Any other ability is treated as a write. The exact ability name and arguments are stored in a user-scoped, conversation-bound transient.
4. The transcript shows the exact stored values. Nothing has run.
5. The browser sends only the proposal ID and conversation ID on approval.
6. The server re-checks the proposal owner, conversation, expiry, pending status, and the ability's own check_permissions() with the stored arguments.
7. The server calls $ability->execute( $stored_args ) as the current user. WordPress validates the input, sanitizes it, checks permissions again, and fires its hooks.
8. The proposal is marked used and a result note is appended to the conversation.

Proposals are single-use and expire after 30 minutes. Conversations expire after two hours.

Audit

• Every executed ability is logged through wp_after_execute_ability.
• Proposals, approvals, denials, and declines are logged explicitly.
• Rows use the new site_agent log type, with the ability name as the operation and the phase in context.
• No post bodies, setting values, credentials, or package URLs are logged.
• External audit plugins can listen to wpai_site_agent_action.

UI

• A minimal React screen with a transcript, composer, and proposal card.
• The proposal card renders the exact stored arguments and the Approve / Decline actions.
• When the write gate is off, the screen clearly says it is read-only and links to the settings page.
• No streaming in this cut; model rounds are buffered.

What is intentionally not included

• Publishing, trash, media uploads, user writes, plugin installation, core/plugin/theme updates, theme switching, and export.
• Each is a reviewed ability away and can be added without changing the agent loop.

Use of AI Tools

AI assistance: Yes
Tool(s): Ollama
Model(s): Deepseek-v4.1-flash:cloud
Used for: Initial implementation, the refactor to the abilities-first design, tests, documentation, and manual verification. The final code, tests, and security behaviour were reviewed and edited by the author.

Testing Instructions

Automated

npm ci
composer install
npm run build
npm run typecheck
npm run test:php

Run the Site Agent e2e spec with the AI plugin active in the wp-env test site:

npx wp-scripts test-playwright --config tests/e2e/playwright.config.ts \
  tests/e2e/specs/experiments/site-agent.spec.js

Validated locally:

• PHP suite: 1937 tests, 5537 assertions, 42 skipped.
• Site Agent suites: 35 tests across the abilities, agent loop, and experiment/gates.
• phpcs and phpstan clean for the new backend code.
• TypeScript typecheck and production build pass.

Manual

1. Open Settings → AI, open the settings menu, and enable Advanced settings.
2. Enable Site Agent. Leave Allow write proposals off.
3. Open Tools → Site Agent.
4. Ask “What version of WordPress and PHP am I running?” and confirm a real answer from ai/site-agent-read-site.
5. Ask “Create a draft titled ‘Site Agent test’.” and confirm the assistant says it cannot while writes are off.
6. Enable Allow write proposals, reload, and ask again. Confirm a proposal card shows the exact title, type, and status, and that no draft exists yet.
7. Click Decline and confirm nothing was created.
8. Ask again, click Approve, and confirm the draft appears under Posts → Drafts.
9. Ask to change the tagline and confirm the proposal shows blogdescription and the exact new value. Approve and verify under Settings → General.
10. Open Tools → AI Request Logs, filter by site_agent, and confirm proposal/execute/approval/decline rows exist without content or secret values.

I also tested the above end-to-end on a real WordPress 7.1.3 site with a Google connector, including the read, proposal, approve, decline, settings update, and audit paths.

Screenshots or screencast

Changelog Entry

Added - New Site Agent experiment: a conversational assistant under Tools that reads site information and proposes changes through reviewed WordPress Abilities. Every write is stored as a server-side proposal and executes only after approval. The experiment and its write gate are disabled by default.