refactor: align Chat REST handlers with core Abilities API contract

Replace require_ability/ability_response with a single execute_ability()
helper that follows core's WP_Ability::execute() contract:

- wp_get_ability() directly (no function_exists guard — WP 6.9 minimum)
- Core's execute() handles input validation + permissions + callback
- WP_Error pass-through for core failures
- Legacy { success: false } array shim until abilities return WP_Error

Every handler is now a one-liner: extract params → execute_ability().
No fallback paths, no duplicated logic, no intermediate variables.

Author: chubes4

inc/Api/Chat/Chat.php

@@ -361,24 +361,16 @@ public static function handle_ping( WP_REST_Request $request ) {
 	 * @return WP_REST_Response Response data.
 	 */
 	public static function list_sessions( WP_REST_Request $request ) {
-		$ability = self::require_ability( 'datamachine/list-chat-sessions' );
-		if ( is_wp_error( $ability ) ) {
-			return $ability;
-		}
-
-		$agent_id = PermissionHelper::resolve_scoped_agent_id( $request );
-
-		$result = $ability->execute(
+		return self::execute_ability(
+			'datamachine/list-chat-sessions',
 			array(
 				'user_id'  => get_current_user_id(),
-				'agent_id' => $agent_id,
+				'agent_id' => PermissionHelper::resolve_scoped_agent_id( $request ),
 				'limit'    => (int) $request->get_param( 'limit' ),
 				'offset'   => (int) $request->get_param( 'offset' ),
 				'context'  => $request->get_param( 'context' ),
 			)
 		);
-
-		return self::ability_response( $result, 'list_sessions_failed' );
 	}
 
 	/**
@@ -390,19 +382,13 @@ public static function list_sessions( WP_REST_Request $request ) {
 	 * @return WP_REST_Response|WP_Error Response data or error.
 	 */
 	public static function mark_session_read( WP_REST_Request $request ) {
-		$ability = self::require_ability( 'datamachine/mark-session-read' );
-		if ( is_wp_error( $ability ) ) {
-			return $ability;
-		}
-
-		$result = $ability->execute(
+		return self::execute_ability(
+			'datamachine/mark-session-read',
 			array(
 				'session_id' => sanitize_text_field( $request->get_param( 'session_id' ) ),
 				'user_id'    => get_current_user_id(),
 			)
 		);
-
-		return self::ability_response( $result, 'mark_read_failed' );
 	}
 
 	/**
@@ -412,19 +398,13 @@ public static function mark_session_read( WP_REST_Request $request ) {
 	 * @return WP_REST_Response|WP_Error Response data or error.
 	 */
 	public static function delete_session( WP_REST_Request $request ) {
-		$ability = self::require_ability( 'datamachine/delete-chat-session' );
-		if ( is_wp_error( $ability ) ) {
-			return $ability;
-		}
-
-		$result = $ability->execute(
+		return self::execute_ability(
+			'datamachine/delete-chat-session',
 			array(
 				'session_id' => sanitize_text_field( $request->get_param( 'session_id' ) ),
 				'user_id'    => get_current_user_id(),
 			)
 		);
-
-		return self::ability_response( $result, 'delete_failed' );
 	}
 
 	/**
@@ -434,19 +414,13 @@ public static function delete_session( WP_REST_Request $request ) {
 	 * @return WP_REST_Response|WP_Error Response data or error.
 	 */
 	public static function get_session( WP_REST_Request $request ) {
-		$ability = self::require_ability( 'datamachine/get-chat-session' );
-		if ( is_wp_error( $ability ) ) {
-			return $ability;
-		}
-
-		$result = $ability->execute(
+		return self::execute_ability(
+			'datamachine/get-chat-session',
 			array(
 				'session_id' => sanitize_text_field( $request->get_param( 'session_id' ) ),
 				'user_id'    => get_current_user_id(),
 			)
 		);
-
-		return self::ability_response( $result, 'get_failed' );
 	}
 
 	/**
@@ -681,24 +655,23 @@ private static function resolve_attachment_paths( array $attachments ): array {
 	}
 
 	/**
-	 * Resolve an ability by slug, returning WP_Error if unavailable.
+	 * Execute an ability and return the REST response.
+	 *
+	 * Resolves the ability by slug, calls execute() with the given input,
+	 * and converts the result into a REST response. Handles WP_Error returns
+	 * from core's execute() pipeline (input validation, permissions, callback).
 	 *
-	 * Centralizes the guard so handlers never duplicate the check.
+	 * For ability callbacks that still return { success: false, error: ... }
+	 * arrays (legacy convention), those are mapped to WP_Error. New abilities
+	 * should return WP_Error directly per core best practices.
 	 *
 	 * @since 0.62.0
 	 *
-	 * @param string $slug Ability slug (e.g. 'datamachine/get-chat-session').
-	 * @return \WP_Ability|WP_Error The ability instance or an error.
+	 * @param string $slug  Ability slug (e.g. 'datamachine/get-chat-session').
+	 * @param array  $input Input parameters for the ability.
+	 * @return WP_REST_Response|WP_Error
 	 */
-	private static function require_ability( string $slug ) {
-		if ( ! function_exists( 'wp_get_ability' ) ) {
-			return new WP_Error(
-				'ability_unavailable',
-				__( 'Abilities API not loaded.', 'data-machine' ),
-				array( 'status' => 500 )
-			);
-		}
-
+	private static function execute_ability( string $slug, array $input = array() ) {
 		$ability = wp_get_ability( $slug );
 
 		if ( ! $ability ) {
@@ -710,40 +683,35 @@ private static function require_ability( string $slug ) {
 			);
 		}
 
-		return $ability;
-	}
+		$result = $ability->execute( $input );
 
-	/**
-	 * Convert an ability result array into a REST response.
-	 *
-	 * On success wraps in `{ success: true, data: ... }`.
-	 * On failure maps the error code to an appropriate HTTP status.
-	 *
-	 * @since 0.62.0
-	 *
-	 * @param array  $result           Ability execute() return value.
-	 * @param string $default_error    Fallback error code when result has none.
-	 * @return WP_REST_Response|WP_Error
-	 */
-	private static function ability_response( array $result, string $default_error = 'ability_failed' ) {
-		if ( ! empty( $result['success'] ) ) {
-			return rest_ensure_response(
-				array(
-					'success' => true,
-					'data'    => $result,
-				)
-			);
+		// Core's execute() returns WP_Error for validation/permission/callback failures.
+		if ( is_wp_error( $result ) ) {
+			return $result;
 		}
 
-		$error_code = $result['error'] ?? $default_error;
+		// Legacy convention: ability callbacks return { success: false, error: ... }.
+		// Map to WP_Error until all abilities are migrated to return WP_Error directly.
+		if ( is_array( $result ) && isset( $result['success'] ) && ! $result['success'] ) {
+			$error_code = $result['error'] ?? 'ability_failed';
 
-		$status_map = array(
-			'session_not_found'    => 404,
-			'session_access_denied' => 403,
-		);
+			$status_map = array(
+				'session_not_found'     => 404,
+				'session_access_denied' => 403,
+			);
 
-		$status = $status_map[ $error_code ] ?? 500;
+			return new WP_Error(
+				$error_code,
+				$result['error'] ?? 'Ability execution failed.',
+				array( 'status' => $status_map[ $error_code ] ?? 500 )
+			);
+		}
 
-		return new WP_Error( $error_code, $result['error'] ?? $default_error, array( 'status' => $status ) );
+		return rest_ensure_response(
+			array(
+				'success' => true,
+				'data'    => $result,
+			)
+		);
 	}
 }