Proposal: Add ability anotations

includes/abilities-api.php

@@ -25,7 +25,7 @@
  *                                  alphanumeric characters, dashes and the forward slash.
  * @param array<string,mixed> $args An associative array of arguments for the ability. This should include
  *                                  `label`, `description`, `input_schema`, `output_schema`, `execute_callback`,
- *                                  `permission_callback`, `meta`, and `ability_class`.
+ *                                  `permission_callback`, `annotations`, `meta`, and `ability_class`.
  * @return ?\WP_Ability An instance of registered ability on success, null on failure.
  *
  * @phpstan-param array{
@@ -35,6 +35,7 @@
  *   permission_callback?: callable( mixed $input= ): (bool|\WP_Error),
  *   input_schema?: array<string,mixed>,
  *   output_schema?: array<string,mixed>,
+ *   annotations?: array<string,mixed>,
  *   meta?: array<string,mixed>,
  *   ability_class?: class-string<\WP_Ability>,
  *   ...<string, mixed>

includes/abilities-api/class-wp-abilities-registry.php

@@ -57,6 +57,7 @@ final class WP_Abilities_Registry {
 	 *   permission_callback?: callable( mixed $input= ): (bool|\WP_Error),
 	 *   input_schema?: array<string,mixed>,
 	 *   output_schema?: array<string,mixed>,
+	 *   annotations?: array<string,mixed>,
 	 *   meta?: array<string,mixed>,
 	 *   ability_class?: class-string<\WP_Ability>,
 	 *   ...<string, mixed>

includes/abilities-api/class-wp-ability.php

@@ -19,6 +19,29 @@
  * @see WP_Abilities_Registry
  */
 class WP_Ability {
+	/**
+	 * The default ability annotations.
+	 * They are not guaranteed to provide a faithful description of ability behavior.
+	 *
+	 * @since n.e.x.t
+	 * @var array<string,(bool|string)>
+	 */
+	protected static $default_annotations = array(
+		// Instructions on how to use the ability.
+		'instructions' => '',
+		// If true, the ability does not modify its environment.
+		'readonly'     => false,
+		/*
+		 * If true, the ability may perform destructive updates to its environment.
+		 * If false, the ability performs only additive updates.
+		 */
+		'destructive'  => true,
+		/*
+		 * If true, calling the ability repeatedly with the same arguments will have no additional effect
+		 * on its environment.
+		 */
+		'idempotent'   => false,
+	);
 
 	/**
 	 * The name of the ability, with its namespace.
@@ -77,6 +100,14 @@ class WP_Ability {
 	 */
 	protected $permission_callback;
 
+	/**
+	 * The ability annotations.
+	 *
+	 * @since n.e.x.t
+	 * @var array<string,(bool|string)>
+	 */
+	protected $annotations = array();
+
 	/**
 	 * The optional ability metadata.
 	 *
@@ -99,7 +130,7 @@ class WP_Ability {
 	 * @param string              $name The name of the ability, with its namespace.
 	 * @param array<string,mixed> $args An associative array of arguments for the ability. This should
 	 *                                  include `label`, `description`, `input_schema`, `output_schema`,
-	 *                                  `execute_callback`, `permission_callback`, and `meta`.
+	 *                                  `execute_callback`, `permission_callback`, `annotations`, and `meta`.
 	 */
 	public function __construct( string $name, array $args ) {
 		$this->name = $name;
@@ -147,6 +178,7 @@ public function __construct( string $name, array $args ) {
 	 *   permission_callback: callable( mixed $input= ): (bool|\WP_Error),
 	 *   input_schema?: array<string,mixed>,
 	 *   output_schema?: array<string,mixed>,
+	 *   annotations?: array<string,mixed>,
 	 *   meta?: array<string,mixed>,
 	 *   ...<string, mixed>,
 	 * } $args
@@ -190,12 +222,24 @@ protected function prepare_properties( array $args ): array {
 			);
 		}
 
+		if ( isset( $args['annotations'] ) && ! is_array( $args['annotations'] ) ) {
+			throw new \InvalidArgumentException(
+				esc_html__( 'The ability properties should provide a valid `annotations` array.' )
+			);
+		}
+
 		if ( isset( $args['meta'] ) && ! is_array( $args['meta'] ) ) {
 			throw new \InvalidArgumentException(
 				esc_html__( 'The ability properties should provide a valid `meta` array.' )
 			);
 		}
 
+		// Set defaults for optional args.
+		$args['annotations'] = wp_parse_args(
+			$args['annotations'] ?? array(),
+			static::$default_annotations
+		);
+
 		return $args;
 	}
 
@@ -255,6 +299,17 @@ public function get_output_schema(): array {
 		return $this->output_schema;
 	}
 
+	/**
+	 * Retrieves the annotations for the ability.
+	 *
+	 * @since n.e.x.t
+	 *
+	 * @return array<string,(bool|string)> The annotations for the ability.
+	 */
+	public function get_annotations(): array {
+		return $this->annotations;
+	}
+
 	/**
 	 * Retrieves the metadata for the ability.
 	 *

includes/rest-api/endpoints/class-wp-rest-abilities-list-controller.php

@@ -191,6 +191,7 @@ public function prepare_item_for_response( $ability, $request ) {
 			'description'   => $ability->get_description(),
 			'input_schema'  => $ability->get_input_schema(),
 			'output_schema' => $ability->get_output_schema(),
+			'annotations'   => $ability->get_annotations(),
 			'meta'          => $ability->get_meta(),
 		);
 
@@ -264,6 +265,12 @@ public function get_item_schema(): array {
 					'context'     => array( 'view', 'edit' ),
 					'readonly'    => true,
 				),
+				'annotations'   => array(
+					'description' => __( 'Annotations for the ability.' ),
+					'type'        => 'object',
+					'context'     => array( 'view', 'edit' ),
+					'readonly'    => true,
+				),
 				'meta'          => array(
 					'description' => __( 'Meta information about the ability.' ),
 					'type'        => 'object',

includes/rest-api/endpoints/class-wp-rest-abilities-run-controller.php

@@ -54,8 +54,8 @@ public function register_routes(): void {
 					),
 				),
 
-				// TODO: We register ALLMETHODS because at route registration time, we don't know
-				// which abilities exist or their types (resource vs tool). This is due to WordPress
+				// TODO: We register ALLMETHODS because at route registration time, we don't know which abilities
+				// exist or their annotations (`destructive`, `idempotent`, `readonly`). This is due to WordPress
 				// load order - routes are registered early, before plugins have registered their abilities.
 				// This approach works but could be improved with lazy route registration or a different
 				// architecture that allows type-specific routes after abilities are registered.
@@ -90,23 +90,23 @@ public function run_ability_with_method_check( $request ) {
 			);
 		}
 
-		// Check if the HTTP method matches the ability type.
-		$meta   = $ability->get_meta();
-		$type   = isset( $meta['type'] ) ? $meta['type'] : 'tool';
-		$method = $request->get_method();
+		// Check if the HTTP method matches the ability annotations.
+		$annotations = $ability->get_annotations();
+		$is_readonly = ! empty( $annotations['readonly'] );
+		$method      = $request->get_method();
 
-		if ( 'resource' === $type && 'GET' !== $method ) {
+		if ( $is_readonly && 'GET' !== $method ) {
 			return new \WP_Error(
 				'rest_ability_invalid_method',
-				__( 'Resource abilities require GET method.' ),
+				__( 'Read-only abilities require GET method.' ),
 				array( 'status' => 405 )
 			);
 		}
 
-		if ( 'tool' === $type && 'POST' !== $method ) {
+		if ( ! $is_readonly && 'POST' !== $method ) {
 			return new \WP_Error(
 				'rest_ability_invalid_method',
-				__( 'Tool abilities require POST method.' ),
+				__( 'Abilities that perform updates require POST method.' ),
 				array( 'status' => 405 )
 			);
 		}

packages/client/README.md

@@ -28,13 +28,13 @@ const { getAbilities, getAbility, executeAbility } = wp.abilities;
 const abilities = await getAbilities();
 
 // Get a specific ability
-const ability = await getAbility('my-plugin/my-ability');
+const ability = await getAbility( 'my-plugin/my-ability' );
 
 // Execute an ability
-const result = await executeAbility('my-plugin/my-ability', {
+const result = await executeAbility( 'my-plugin/my-ability', {
   param1: 'value1',
   param2: 'value2',
-});
+} );
 ```
 
 ### Using with React and WordPress Data
@@ -47,24 +47,24 @@ import { store as abilitiesStore } from '@wordpress/abilities';
 
 function MyComponent() {
   const abilities = useSelect(
-    (select) => select(abilitiesStore).getAbilities(),
+    ( select ) => select( abilitiesStore ).getAbilities(),
     []
   );
 
   const specificAbility = useSelect(
-    (select) => select(abilitiesStore).getAbility('my-plugin/my-ability'),
+    ( select ) => select( abilitiesStore ).getAbility( 'my-plugin/my-ability' ),
     []
   );
 
   return (
     <div>
       <h2>All Abilities</h2>
       <ul>
-        {abilities.map((ability) => (
-          <li key={ability.name}>
-            <strong>{ability.label}</strong>: {ability.description}
+        { abilities.map( ( ability ) => (
+          <li key={ ability.name }>
+            <strong>{ ability.label }</strong>: { ability.description }
           </li>
-        ))}
+        ) ) }
       </ul>
     </div>
   );
@@ -81,38 +81,38 @@ Returns all registered abilities. Automatically handles pagination to fetch all
 
 ```javascript
 const abilities = await getAbilities();
-console.log(`Found ${abilities.length} abilities`);
+console.log( `Found ${ abilities.length } abilities` );
 ```
 
 #### `getAbility(name: string): Promise<Ability | null>`
 
 Returns a specific ability by name, or null if not found.
 
 ```javascript
-const ability = await getAbility('my-plugin/create-post');
-if (ability) {
-  console.log(`Found ability: ${ability.label}`);
+const ability = await getAbility( 'my-plugin/create-post' );
+if ( ability ) {
+  console.log( `Found ability: ${ ability.label }` );
 }
 ```
 
 #### `executeAbility(name: string, input?: Record<string, any>): Promise<any>`
 
-Executes an ability with optional input parameters. The HTTP method is automatically determined based on the ability's type:
+Executes an ability with optional input parameters. The HTTP method is automatically determined based on the ability's annotations:
 
-- `resource` type abilities use GET (read-only operations)
-- `tool` type abilities use POST (write operations)
+- `readonly` abilities use GET (read-only operations)
+- regular abilities use POST (write operations)
 
 ```javascript
-// Execute a resource ability (GET)
-const data = await executeAbility('my-plugin/get-data', {
+// Execute a read-only ability (GET)
+const data = await executeAbility( 'my-plugin/get-data', {
   id: 123,
-});
+} );
 
-// Execute a tool ability (POST)
-const result = await executeAbility('my-plugin/create-item', {
+// Execute a regular ability (POST)
+const result = await executeAbility( 'my-plugin/create-item', {
   title: 'New Item',
   content: 'Item content',
-});
+} );
 ```
 
 ### Store Selectors

packages/client/src/__tests__/api.test.ts

@@ -259,12 +259,12 @@ describe( 'API functions', () => {
 			).rejects.toThrow( 'invalid input' );
 		} );
 
-		it( 'should execute a resource-type ability via GET', async () => {
+		it( 'should execute a read-only ability via GET', async () => {
 			const mockAbility: Ability = {
-				name: 'test/resource',
-				label: 'Resource Ability',
-				description: 'Test resource ability',
-				meta: { type: 'resource' },
+				name: 'test/read-only',
+				label: 'Read-only Ability',
+				description: 'Test read-only ability.',
+				annotations: { readonly: true },
 				input_schema: {
 					type: 'object',
 					properties: {
@@ -280,27 +280,27 @@ describe( 'API functions', () => {
 				getAbility: mockGetAbility,
 			} );
 
-			const mockResponse = { data: 'resource data' };
+			const mockResponse = { data: 'read-only data' };
 			( apiFetch as unknown as jest.Mock ).mockResolvedValue(
 				mockResponse
 			);
 
 			const input = { id: '123', format: 'json' };
-			const result = await executeAbility( 'test/resource', input );
+			const result = await executeAbility( 'test/read-only', input );
 
 			expect( apiFetch ).toHaveBeenCalledWith( {
-				path: '/wp/v2/abilities/test/resource/run?input%5Bid%5D=123&input%5Bformat%5D=json',
+				path: '/wp/v2/abilities/test/read-only/run?input%5Bid%5D=123&input%5Bformat%5D=json',
 				method: 'GET',
 			} );
 			expect( result ).toEqual( mockResponse );
 		} );
 
-		it( 'should execute a resource-type ability with empty input', async () => {
+		it( 'should execute a read-only ability with empty input', async () => {
 			const mockAbility: Ability = {
-				name: 'test/resource',
-				label: 'Resource Ability',
-				description: 'Test resource ability',
-				meta: { type: 'resource' },
+				name: 'test/read-only',
+				label: 'Read-only Ability',
+				description: 'Test read-only ability.',
+				annotations: { readonly: true },
 				input_schema: { type: 'object' },
 				output_schema: { type: 'object' },
 			};
@@ -310,15 +310,15 @@ describe( 'API functions', () => {
 				getAbility: mockGetAbility,
 			} );
 
-			const mockResponse = { data: 'all resources' };
+			const mockResponse = { data: 'read-only data' };
 			( apiFetch as unknown as jest.Mock ).mockResolvedValue(
 				mockResponse
 			);
 
-			const result = await executeAbility( 'test/resource', {} );
+			const result = await executeAbility( 'test/read-only', {} );
 
 			expect( apiFetch ).toHaveBeenCalledWith( {
-				path: '/wp/v2/abilities/test/resource/run?',
+				path: '/wp/v2/abilities/test/read-only/run?',
 				method: 'GET',
 			} );
 			expect( result ).toEqual( mockResponse );

packages/client/src/api.ts

@@ -176,8 +176,7 @@ async function executeServerAbility(
 	ability: Ability,
 	input: AbilityInput
 ): Promise< AbilityOutput > {
-	const isResource = ability.meta?.type === 'resource';
-	const method = isResource ? 'GET' : 'POST';
+	const method = !! ability.annotations?.readonly ? 'GET' : 'POST';
 
 	let path = `/wp/v2/abilities/${ ability.name }/run`;
 	const options: {