Abilities API

Abilities API

OpenWP integrates with the WordPress Abilities API (introduced in WordPress 6.9) to expose its actions as discoverable, executable abilities for third-party AI agents.

Overview

The Ability_Bootstrap class (inc/Abilities/Ability_Bootstrap.php) bridges OpenWP actions to the WordPress Abilities API, making them discoverable and executable through the standard WordPress infrastructure.

How It Works

WordPress Abilities API
    │
    ├── wp_abilities_api_categories_init → Register 14 ability categories
    └── wp_abilities_api_init           → Register all OpenWP actions as abilities

Registration Flow

For each action in Action_Registry:

1. Generate ability name: openwp/{action-key} (e.g., openwp/wp-create-post)
2. Determine category from action's domain category or risk level
3. Map action schema to ability input schema
4. Set execute_callback to route through Action_Executor
5. Set permission_callback to check openwp_run_agent + action capability
6. Build behavior annotations (readonly, destructive, idempotent)

Ability Categories

Domain Categories

Category	Description
openwp/content	Posts, pages, custom post types
openwp/taxonomy	Categories, tags, custom taxonomies
openwp/media	Media library operations
openwp/users	User management
openwp/settings	WordPress options
openwp/plugins	Plugin lifecycle
openwp/themes	Theme lifecycle
openwp/database	Database maintenance and queries
openwp/comments	Comment moderation
openwp/memory	Agent memory storage

Risk-Level Fallback Categories

Used when no domain category is set on an action:

• openwp-risk-low
• openwp-risk-medium
• openwp-risk-high
• openwp-risk-critical

Behavior Annotations

Each ability includes MCP-style annotations:

[
    'readonly'    => !$mutates,           // true for read-only actions
    'destructive' => $is_destructive,     // true for high-risk mutating actions
    'idempotent'  => $mutates ? null : true,  // true for read-only
]

REST Discoverability

• Read-only, low-risk abilities have show_in_rest: true
• Mutating or higher-risk abilities have show_in_rest: false

This prevents AI agents from accidentally discovering and calling destructive abilities through the REST API.

Permission Model

Two checks are enforced:

1. User must have openwp_run_agent capability
2. User must have the action's required WordPress capability (e.g., edit_posts, manage_options)

Both checks must pass for the ability to be executable.

Execution Path

When an ability is called via the WordPress Abilities API:

wp_execute_ability('openwp/wp-create-post', $input)
    │
    ├── permission_callback → can_execute_action_ability()
    │   ├── Check openwp_run_agent cap
    │   └── Check action-specific cap
    │
    └── execute_callback → execute_action_ability()
        ├── Create ActionContext (source: 'wp_ability')
        └── Action_Executor::execute()
            ├── Schema validation
            ├── Policy evaluation
            ├── Backup (if required)
            ├── Execute callback
            └── Audit log

Output Schema

When an action defines an output_schema, it is passed through to the ability registration, enabling AI agents to understand the expected response format.