Adds support for simple Ability versioning

[JasonTheAdams]

Trac ticket: 64345

This adds the ability for an Ability name to have a version. Both of these would be valid names:

• wp/generate-featured-image
• wp/v1/generate-featured-image

As noted in the Trac ticket, this was intended, but we didn't catch that the validation regex rejects this.

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

Core Committers: Use this line as a base for the props when committing in SVN:

Props jason_the_adams, westonruter, jorgefilipecosta, flixos90, antju, justlevine.

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[JasonTheAdams]

I'm tempted to also add two methods to WP_Ability since these are enforced conventions.

• WP_Ability::get_namespace() — returns "wp"
• WP_Ability::get_version() — returns null for first example and v1 for second

[github-actions]

Test using WordPress Playground

The changes in this pull request can previewed and tested using a WordPress Playground instance.

WordPress Playground is an experimental project that creates a full WordPress instance entirely within the browser.

Some things to be aware of

• The Plugin and Theme Directories cannot be accessed within Playground.
• All changes will be lost when closing a tab with a Playground instance.
• All changes will be lost when refreshing the page.
• A fresh instance is created each time the link below is clicked.
• Every time this pull request is updated, a new ZIP file containing all changes is created. If changes are not reflected in the Playground instance,
  it's possible that the most recent build failed, or has not completed. Check the list of workflow runs to be sure.

For more details about these limitations and more, check out the Limitations page in the WordPress Playground documentation.

Test this pull request with WordPress Playground.

[westonruter]

According to the example, where the second path segment is v1, the regex would seem to rather be:

Suggested change

	if ( ! preg_match( '/^[a-z0-9-]+\/([a-z0-9-]+\/)?[a-z0-9-]+$/', $name ) ) {
	if ( ! preg_match( '/^[a-z0-9-]+\/(v[0-9]+\/)?[a-z0-9-]+$/', $name ) ) {

[JasonTheAdams]

I thought about doing that but wasn't sure if we should have a direct opinion about how people version things. We're also not enforcing a a.b.c structure, either.

[jorgefilipecosta]

Having an opinion may make it easier to in the future just return the latest version for some ability. If we don't enforce a structure our only option is to rely on string sorting which has unexpected results e.g: v3 is higher than v13. I expected because of keeping context small/relevant for LLMS having a function that just returns the last version of each ability will be something common.

I'm tempted to force an integer value for the version as it seems to be the simplest approach with obvious outcomes when sorted. We could also support something like v[0-9]+(.[0-9]+){,2} if we want to be more flexible and support vX.Y, vX.Y.Z, where X, Y, Z are considered integers for sorting purposes.

[JasonTheAdams]

You are right, and honestly I want to do that. This allows for things like version_compare being used. If someone doesn't follow that then I guess it could have odd behavior.

This does bring my deprecation PR to mind as well, which could refer to a version.

I feel like there are two directions we could go:

1. No strict boundaries around versioning; just let implementers do their own thing
2. Enforce PHP versioning so we can use versioning functions

[jorgefilipecosta]

I think we should enforce a versioning system but I don't think we need the full php version system something like v10.X.Y where both X and Y are optional should be enough, consumers of abilities like the JS client package, or something consuming the rest API in a random programming language may also need to compare versions, and having the full php versioning system with RC etc adds more complexity.

[jorgefilipecosta]

If start with a strict subset in the future we can expand, but starting broad and then stricting may not be possible that's also the reason I would prefer a stricter approach at the beginning.

[jorgefilipecosta]

We should update the ticket number to 64345.

[jorgefilipecosta]

The PR is in a good shape, I think after updating the regex to be stricter we can merge this update.

[felixarntz]

Copy-pasting from Slack thread:

I don't think we should encourage versioned abilities.

It goes against WordPress Core philosophies, and I think it's going to lead to a somewhat messy ecosystem.

FWIW: REST endpoints tend to have versions, but they're almost never used. In other words, the fact that it's called wp/v2 in Core endpoints is pointless, they haven't been updated ever since they were introduced. Which confirms the point that we shouldn't have versions.

[felixarntz]

Marking as requesting changes due to the ongoing discussion whether we should do this - in practice this is probably more of a "requesting to close PR" feedback, but all pending the discussion outcome.

[antunjurkovic-collab]

Strong +1 to @felixarntz and @justlevine on keeping the Ability identifier stable.

From an agent perspective (MCP tools / AI agents), stable identifiers are critical for autonomy and long-term usability.

Hard versioning risk (wp/v1/generate-featured-image):
If an agent is prompted or fine-tuned to call wp/v1/generate-featured-image and the site later moves to wp/v2/…, the agent just hits “tool not found”. It has no obvious way to discover the new version or know it’s the correct replacement. The namespace becomes brittle.

Schema-evolution approach (wp/generate-featured-image + metadata):
If the identifier stays stable (wp/generate-featured-image) and versioning/deprecation is expressed in metadata (e.g. meta.version, deprecation_reason):

The agent calls the same Ability name.

The system can respond with a warning or schema change (e.g. “field X is deprecated, use Y”).

The agent (or client library) can self-heal by updating the payload and retrying, without changing the identifier it was trained on.

This matches what we’re seeing in most agent/tool ecosystems:

Identifier = intent / capability (stable).

Schema + metadata = what evolves (version, deprecation, preferred args).

Keeping the Ability name evergreen and pushing evolution into the schema/metadata gives us better discovery, fewer hard breaks, and a much cleaner story for AI and non-AI clients alike.

[justlevine]

Shared my feedback directly to trac, since PR comments are one-directional: https://core.trac.wordpress.org/ticket/64345#comment:5

[JasonTheAdams]

Thanks for all the really great thoughts! I definitely see where folks are coming from. To help make things concrete, let me frame an example:

In my mind there are two sides to this, and they approach the same issue:

• Versioning
• Deprecation

Let's say I'm GiveWP and I have a givewp/create-donation ability. Later, we add (true story) Campaigns, and make it so that every donation must be associated with a campaign via a campaign_id. Ok, so now we need to update the ability. This means two things:

First, I'll need to create a new ability so the old one still works to at least some extent, or for a certain period of time. This presents the new dilemma: what do I name the ability? givewp/create-donation-with-campaign? givewp/cteate-donation-final? It's still the same thing, it just has different input and output parameters.
Second, I want to communicate this change to users. They should switch to the new ability. How do I communicate that an ability will eventually be removed, and how do I communicate what the new ability to use is?

Versioning helps with the first via givewp/v1/create-donation and then givewp/v2/create-donation. Deprecation helps with the second with the ability to mark an ability with deprecation and an ID to the new one.

---

Now, one could argue that in this case GiveWP should somehow make the Ability backwards compatibility. I'm not sure how that would be possible, but in any case it forces architectural philosophy on the developer. We don't know them or their market, so I want to avoid that.

I like @justlevine's (on trac) creative approach to include versioning as part of a single ability, but this actually touches on a point I just made elsewhere today: for maximize an Ability's chances of working well multi-contextually, simplicity is key. Having Abilities that grow in complexity like that hurts discoverability and reduces the chances of it working easily in many contexts.

As a note, it "subdomains" in the Ability name is effectively what's being proposed here, at least in its simplest form. I'm leery about trying to shove in too much of a versioning concept, which is why I'm presenting a "versioned" Ability as actually multiple Abilities. It's not one that's versioned; it's many that include an optional version as part of the namespace. I emphasize optional because if in core, for example, we philosophically do not want to version and commit to backwards compatibility, then we can omit the version and call it a day.

The closest I get to a concept of versioning is (and I definitely won't die on this hill) the idea of a "latest" Ability. That is, if we have givewp/v1/create-donation and givewp/v2/create-donation then givewp/latest/create-donation would always point to the last version. The only reason this comes to mind is for cases like MCP where it would be better to only create a tool for the latest Ability. But, honest, I think this is quite optional.

I'd love to hear from folks using this GiveWP example as reference, or any other scenarios others want to introduce, to help this conversation be as concrete as possible. 😄

[jorgefilipecosta]

Sharing here for discussion an alternative approach following the same pattern we use for blocks in Gutenberg, which has been working for many years.

The attributes of a block may also change, some removed, some added, but we need to keep supporting blocks created using old versions relying on old attributes, etc. So it is a very similar scenario.

Basically, abilities would not specify a version; they would be registered normally but could have an array with old deprecated abilities:

wp_register_ability(
	'plugin/my-ability',
	array(
		'label'               => __( 'My ability' ),
		'description'         => __( 'My ability).' ),
		'input_schema'        => array(...),
		'output_schema'       => array(...),
		'execute_callback'    => ...,
		'permission_callback' => ...,
		'deprecated' => array(
			// Deprecated in version 1.1
			array(
				'input_schema'       => array(...),
				'output_schema'      => array(...),
				'execute_callback'   => ...,
				'permission_callback' => ...,
			),
			// Deprecated in version 1.0
			array(
				'input_schema'       => array(...),
				'output_schema'      => array(...),
				'execute_callback'   => ...,
				'permission_callback' => ...,
			),
		),
	)
);

Consumers of an ability relying on a specific input or output schema: e.g., because they programmatically use the output or because they document the input schema in an LLM prompt, would specify the version of the schemas they are relying on:

$result = wp_execute_ability( 'plugin/my-ability', $args, $schemas );

If the expected schema does not match the current one, the system would look for a deprecated version matching the expected schemas and use the corresponding callbacks. If no schemas are specified, it would use the current version, provided the input args match its schema; otherwise, it would automatically use a deprecated version whose schema matches the input args.

For example renaming an input parameter would be easy deprecation calling the new callback mapping the old name to the new one. For people using the old input things would still automatically work even if they don't specify the schema they are expecting version etc.

[JasonTheAdams]

Ohhh, now that's fascinating, @jorgefilipecosta. I'll have to chew on that. 🤔