Add core/media-query ability by jorgefilipecosta · Pull Request #1098 · WordPress/ai

jorgefilipecosta · 2026-10-01T22:33:41Z

What?

Closes #1062

Adds core/media-query, a read-only ability for media library items.

Why?

Agents can read posts, users, and settings through abilities, but not the media library.

How?

The ability lives in includes/Abilities/Media/Media.php, behind the Custom Abilities experiment.
It follows the read path of /wp/v2/media: the posts controller's get_items(), get_item(), and permission checks, and the attachments controller's query and fields. Error codes are REST's with media_ in place of rest_.
REST's quirks are kept:
- totals count items the caller cannot read;
- exclude is ignored when include is given;
- MIME types the site does not allow are ignored;
- the generated caption of a password-protected item stays gated, even for editors, while its rendered description is not.
Two modes: one item by id, or a collection that returns { media, total, total_pages }.
- Filters: search, media_type, mime_type, parent, author, include, exclude and status.
- Sorting: orderby and order.
- Pages: page and per_page.
fields picks the fields, with a lean default set, and id is always returned. title, caption and description are flattened to *_raw and *_rendered. Asking for a raw field reads in the edit context, so a collection only lists the items the caller can edit.
The tests port the core attachments controller's read tests under their core names. They add the ability's modes, string input, and roles from administrator to logged out, plus an e2e spec through the client-side Abilities API.

Differences from REST:

Callers must be logged in.
Attachments hidden from REST, which have no REST route, are denied.
A missing item is denied like an unreadable one.
Not supported:
- the date filters, slug, offset, author_exclude, parent_exclude;
- the taxonomy filters;
- search_columns, search_semantics, orderby=include_slugs;
- context, _fields and password.
Not returned:
- guid, type, class_list, featured_media, comment_status, ping_status, meta, template, permalink_template, generated_slug;
- taxonomy terms and register_rest_field() fields;
- the edit-only media processing fields (missing_image_sizes, exif_orientation, image_quality, image_output_format, image_save_progressive).
Errors:
- a status the caller may not query is media_invalid_param (REST's rest_invalid_param);
- permission failures are ability_invalid_permissions;
- the input is validated and permissions are checked before statuses, so a request that fails more than one check can report a different error first.
link and source_url are always strings.
No _links, embedding, headers, or rest_* filters.

Testing Instructions

Enable the Custom Abilities experiment.
In the block editor console, run the snippet from this comment with IDs from your site.
npm run test:php -- --filter 'MediaTest|Gated_AbilitiesTest'
npm run test:e2e -- tests/e2e/specs/abilities/core-media-query.spec.js

Changelog Entry

Added - New core/media-query ability that mirrors the REST API media endpoint.

github-actions · 2026-10-01T22:39:03Z

✅ WordPress Plugin Check Report

✅ Status: Passed

📊 Report

All checks passed! No errors or warnings found.

🤖 Generated by WordPress Plugin Check Action • Learn more about Plugin Check

codecov · 2026-10-01T22:39:40Z

Codecov Report

❌ Patch coverage is 96.78457% with 20 lines in your changes missing coverage. Please review.
✅ Project coverage is 82.27%. Comparing base (da700e0) to head (6914c20).

Files with missing lines	Patch %	Lines
includes/Abilities/Media/Media.php	96.76%	20 Missing ⚠️

Additional details and impacted files

@@              Coverage Diff              @@
##             develop    #1098      +/-   ##
=============================================
+ Coverage      81.53%   82.27%   +0.73%     
- Complexity      3071     3231     +160     
=============================================
  Files            129      131       +2     
  Lines          12253    12875     +622     
=============================================
+ Hits            9991    10593     +602     
- Misses          2262     2282      +20

Flag	Coverage Δ
unit	`82.27% <96.78%> (+0.73%)`	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

jorgefilipecosta · 2026-10-02T03:58:38Z

Tested in the browser console of the block editor, with the Custom Abilities and Excerpt Generation experiments on (the second one loads the abilities client modules):

const { ready } = await import( '@wordpress/core-abilities' );
await ready;
const { executeAbility } = await import( '@wordpress/abilities' );

const run = ( input ) =>
	executeAbility( 'core/media-query', input ).catch( ( error ) => ( { error: error.code } ) );

// A post and two attachments, the first one attached to the post.
const postId = 610;
const attachedId = 611;
const unattachedId = 612;

// A collection with the default fields.
console.log( 'list', await run( { include: [ attachedId, unattachedId ] } ) );

// One item, with the requested fields.
console.log( 'item', await run( { id: attachedId, fields: [ 'title_rendered', 'caption_raw', 'alt_text', 'post', 'filename', 'media_details' ] } ) );

// Filters, sorting and pages: the second of two matches.
console.log( 'filtered', await run( { media_type: [ 'image' ], mime_type: [ 'image/png' ], search: 'demo', orderby: 'title', order: 'asc', per_page: 1, page: 2, fields: [ 'id', 'title_rendered' ] } ) );

// The items attached to a post.
console.log( 'parent', await run( { parent: [ postId ], fields: [ 'id', 'post' ] } ) );

// Errors.
console.log( 'id with a query', await run( { id: attachedId, per_page: 1 } ) ); // ability_invalid_input
console.log( 'page too far', await run( { include: [ attachedId ], page: 99 } ) ); // media_post_invalid_page_number
console.log( 'relevance without a search', await run( { orderby: 'relevance' } ) ); // media_no_search_term_defined
console.log( 'missing item', await run( { id: 999999999 } ) ); // rest_ability_cannot_execute

Output:

list: both items with the default fields (id, date, slug, title_rendered, alt_text, media_type, mime_type, source_url), total: 2, total_pages: 1.
item: { id, title_rendered, caption_raw, alt_text, media_details, post, filename }, with post: 610.
filtered: the unattached image, total: 2, total_pages: 2.
parent: only the attached image.
The four errors come back with the codes in the comments.

jeffpaul · 2026-10-04T15:00:36Z

@jorgefilipecosta note that I'm holding off on requesting reviews until this comes out of draft status

jorgefilipecosta added 2 commits October 1, 2026 23:33

Add the core/media-query ability

1bf6b0f

Gate core/media-query behind the Custom Abilities experiment

38795f9

jorgefilipecosta added 24 commits October 1, 2026 23:47

Port the core REST attachment read tests

10bd2f1

Add ability tests for core/media-query

1e58951

Add an e2e spec for core/media-query

78673ec

Port the core get item params test

1335f31

Skip the password check on items the user can edit in the edit context

e39950e

Keep the password gate on generated captions in the edit context

c1cc367

Deny every request when attachments are hidden from REST

8540caa

Leave the media type enum out when no MIME types are allowed

1da9b8c

Remove the temporary filters even when a callback throws

f69317e

Reset a bound global post instead of unsetting it

d03481d

Validate collection items against the item schema

5b0cf4f

Correct the page and totals descriptions

57b6e97

Check that a gated caption does not reveal the description

377b85f

Fix a data set label

5345709

Check the status code of a forbidden status list

471cc5a

Stop sweeping uploads the tests never add

722a3d7

Drop e2e filters the PHPUnit tests already cover

56fa89a

Fold the unknown field test into the unsupported input cases

7e3af1d

Drop the title search test the file name search port covers

a0a279d

Drop string inputs the ported tests already cover

00abc5d

Merge the params subset test into its port

ee7dff4

Let create_fixture take post fields and use it for inline fixtures

9c97da8

Use the REST test case's error assertion

c407d60

Register the category through the ability's own fallback in tests

afb11db

Reject unknown output properties like the sibling abilities

ae362ba

jorgefilipecosta added 2 commits October 2, 2026 10:08

Restore the global post the way the content ability does

8f1916c

Describe the page like the content ability

6914c20

jorgefilipecosta mentioned this pull request Oct 2, 2026

Add core/media-upload, core/media-update, and core/media-delete abilities #1104

Draft

jeffpaul added this to the 1.5.0 milestone Oct 4, 2026

jeffpaul mentioned this pull request Oct 4, 2026

Add a core/media-query ability (read-only Media Library coverage) #1062

Open

Navigation Menu

Repository navigation

Add core/media-query ability - #1098

Add core/media-query ability#1098
jorgefilipecosta wants to merge 29 commits into
developfrom
add/core-media-query

jorgefilipecosta commented Oct 1, 2026 •

edited by github-actions Bot

Loading

Uh oh!

github-actions Bot commented Oct 1, 2026

Uh oh!

codecov Bot commented Oct 1, 2026 •

edited

Loading

Uh oh!

jorgefilipecosta commented Oct 2, 2026

Uh oh!

jeffpaul commented Oct 4, 2026

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

jorgefilipecosta commented Oct 1, 2026 • edited by github-actions Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What?

Why?

How?

Testing Instructions

Changelog Entry

Uh oh!

github-actions Bot commented Oct 1, 2026

✅ WordPress Plugin Check Report

📊 Report

Uh oh!

codecov Bot commented Oct 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

jorgefilipecosta commented Oct 2, 2026

Uh oh!

jeffpaul commented Oct 4, 2026

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

jorgefilipecosta commented Oct 1, 2026 •

edited by github-actions Bot

Loading

codecov Bot commented Oct 1, 2026 •

edited

Loading