Register Abilities API for self-healing remediation actions

[claytoncollie]

Problem

The diagnostics abilities proposed in #215 let an AI assistant observe operational problems (stale cache, a stuck scheduled event, a fataling plugin) but not resolve them. An agent that can only report issues still requires a human to log in and act. Exposing a bounded set of safe, auth-gated remediation actions lets an agent close the loop and self-heal common operational problems — turning "the agent noticed the object cache looked stale" into "the agent flushed it and confirmed recovery."

Dependencies

• Add WordPress MCP Adapter package #213 (MCP Adapter package) must be completed first
• Safe mode constants for AI access control #217 (safe mode / access control) should gate these from the start
• Activity log tracking for AI-initiated changes #216 (AI-change audit logging) should cover these actions, not only settings writes
• Complements Register Abilities API for site diagnostics and activity log #215 (diagnostics abilities — the "observe" half of the loop)

Proposal

Register a category of action abilities for common, reversible operational remediations. Each is capability-gated behind WordPress authentication, idempotent where possible, and audit-logged.

Abilities to register

Category: tenup-experience-remediation

Ability Name	Type	Description
tenup/flush-object-cache	write	Flush the persistent object cache
tenup/flush-page-cache	write	Purge the hosting/page cache (provider-aware)
tenup/clear-transients	write	Delete expired (or all) transients
tenup/run-scheduled-event	write	Run a specific due/overdue cron event now
tenup/reschedule-cron	write	Re-register a missing or duplicated scheduled event
tenup/flush-rewrite-rules	write	Regenerate rewrite rules (fixes 404s after structural changes)
tenup/reset-opcache	write	Reset PHP OPcache (clears stale bytecode after a deploy)
tenup/deactivate-plugin	write	Deactivate a single plugin (e.g. one throwing fatals)

This is a starting set — which actions are default-on vs. opt-in is a discussion point (see the umbrella issue).

Design notes

• Provider-aware: page-cache and object-cache flushes should detect the hosting provider (the plugin already has get_hosting_provider()) and call the right mechanism.
• Idempotent + reversible: prefer actions that are safe to repeat and easy to undo. Destructive or irreversible operations (dropping data, deleting users/posts, editing files) are explicitly out of scope.
• Capability mapping: each ability's permission_callback maps to an appropriate capability (e.g. manage_options); never __return_true. The MCP tool can never exceed the authenticated user's caps.
• Verification built in: each action's output should report enough state for the agent to confirm it worked (e.g. cache flushed → report new state), so "act" and "verify" happen in one call.
• Honest annotations: set the destructive / idempotent MCP annotations accurately so clients can surface appropriate confirmations.
• Gated: wrap every registration in the tenup_experience_ai_is_writable() check from Safe mode constants for AI access control #217.

Implementation pattern

Same wp_register_ability() pattern as #214, registered on wp_abilities_api_init, wrapped in the writability gate from #217.

Files

• New: includes/classes/Abilities/Remediation.php
• Modified: 10up-experience.php (instantiate new class)

Verification

1. With write access enabled, ask an AI assistant to "flush the object cache"; confirm the cache is cleared and the action is logged with source: abilities-api.
2. Confirm each action is gated by permission_callback and hidden when TENUP_EXPERIENCE_AI_SAFE_MODE is set.
3. Confirm a "run scheduled event" action executes only the named event and reports its result.
4. Confirm destructive/irreversible operations are not exposed at all.