Automattic\WooCommerce\Internal\Abilities
AbilitiesTracking{} │ WC 11.3.0
Records a Tracks event for each WooCommerce ability invocation.
Hooks only collect data in memory. Events are sent once per request on shutdown through the batched Tracks client. Ability input and output are never recorded, except the name of a registered ability an agent looks up through the MCP Adapter.
WordPress 7.0 only fires hooks around successful executions, so failures there are recorded on shutdown with an unknown error code and no duration. WordPress 7.1+ hooks expose the other outcomes. A missing input schema is returned before those hooks and stays unknown.
Хуков нет.
Использование
$AbilitiesTracking = new AbilitiesTracking(); // use class methods
Методы
- public __construct()
- public handle_init()
- public handle_mcp_adapter_pre_tool_call( $args )
- public handle_rest_request_after_callbacks( $response, $handler, $request )
- public handle_rest_request_before_callbacks( $response, $handler, $request )
- public handle_shutdown()
- public handle_wp_ability_execute_result( $result, $ability_name )
- public handle_wp_ability_invoked( $ability_name )
- public handle_wp_ability_normalize_input( $input, $ability_name )
- public handle_wp_ability_permission_result( $permission, $ability_name )
- public handle_wp_ability_validate_input( $is_valid, $input, $ability_name )
- public handle_wp_ability_validate_output( $is_valid, $output, $ability_name )
- public handle_wp_after_execute_ability( $ability_name, $input = null )
- public handle_wp_before_execute_ability( $ability_name )
- public handle_wp_pre_execute_ability( $pre, $ability_name )
- private add_event( array $frame, $outcome, bool $has_duration )
- private close_frame( $ability_name, bool $executing, $result )
- private create_frame( string $ability_name, bool $executing )
- private find_frame( string $ability_name, bool $executing )
- private flush_events()
- private static get_auth_method()
- private get_channel()
- private static get_error_code( WP_Error $error )
- private static get_event_ability_name( string $ability_name )
- private get_external_client()
- private get_mcp_client_name_from_request()
- private static get_mcp_client_name_from_session()
- private get_rest_namespace()
- private static get_validation_error( $is_valid, string $default_code )
- private static is_a11n()
- private static is_jetpack_signed_request()
- private is_json_rpc_tool_call()
- protected is_long_running_process()
- private is_mcp_request()
- private static is_tracked_ability( $ability_name )
- private static is_tracking_allowed()
- private static normalize_value( string $value, ?int $max_length = 64 )
- private open_frame( string $ability_name, bool $executing )
- private queue_event( string $event_name, array $event, ?float $started = null )
- private record_discovery( $ability_name, $input )
- private resolve_external_client()
- protected send_event( array $properties )
- protected send_queued_pixels()
Список изменений
| С версии 11.3.0 | Введена. |
Код AbilitiesTracking{} AbilitiesTracking{} WC 11.3.0
class AbilitiesTracking {
/**
* Tracks event name, without the `wcadmin_` prefix.
*
* @var string
*/
private const EVENT_NAME = 'ability_called';
/**
* Tracks event for agents looking up abilities through the MCP Adapter, without the `wcadmin_` prefix.
*
* @var string
*/
private const DISCOVERY_EVENT_NAME = 'ability_discovered';
/**
* Channels whose calls are recorded: agent entry points, not plugin internals.
*
* @var string[]
*/
private const TRACKED_CHANNELS = array( 'mcp', 'rest', 'cli' );
/**
* Only abilities in this namespace are tracked.
*
* @var string
*/
private const ABILITY_PREFIX = 'woocommerce/';
/**
* Upper bound of tracked invocations per request, to keep memory and the shutdown flush bounded.
*
* @var int
*/
private const MAX_EVENTS_PER_REQUEST = 25;
/**
* Matches the core Abilities API route that runs an ability.
*
* @var string
*/
private const ABILITIES_RUN_ROUTE_REGEX = '#^/wp-abilities/v\d+/abilities/.+/run$#i';
/**
* Known MCP clients, as normalized name tokens mapped to the recorded value. Checked in order.
*
* @var array<string, string>
*/
private const KNOWN_MCP_CLIENTS = array(
'claude_code' => 'claude_code',
'claude' => 'claude',
'codex' => 'codex',
'chatgpt' => 'chatgpt',
'openai' => 'chatgpt',
'cursor' => 'cursor',
'windsurf' => 'windsurf',
'vscode' => 'vscode',
'visual_studio_code' => 'vscode',
'copilot' => 'copilot',
'gemini' => 'gemini',
'cline' => 'cline',
'goose' => 'goose',
'zed' => 'zed',
'mcp_inspector' => 'mcp_inspector',
'mcp_wordpress_remote' => 'mcp_wordpress_remote',
);
/**
* Value sent for properties that don't apply or are unknown.
*
* @var string
*/
private const NONE = 'none';
/**
* Open ability invocations, innermost last.
*
* @var array<int, array{name: string, channel: string, rest_namespace: string, external_client: string, start: float, executing: bool}>
*/
private array $frames = array();
/**
* Tracks properties of events waiting to be sent.
*
* @var array<int, array<string, mixed>>
*/
private array $events = array();
/**
* Whether this request is an MCP request: an MCP Adapter tool call happened, or the request has MCP HTTP headers.
*
* @var bool|null Null until checked.
*/
private ?bool $is_mcp_request = null;
/**
* MCP client recorded with events, resolved when first needed.
*
* @var string|null
*/
private ?string $external_client = null;
/**
* REST requests being dispatched, outermost first.
*
* @var array<int, WP_REST_Request<array<string, mixed>>>
*/
private array $rest_requests = array();
/**
* Number of invocations opened when each REST request in $rest_requests started dispatching.
*
* @var int[]
*/
private array $rest_frames_opened = array();
/**
* Number of events not recorded because the per-request limit was reached.
*
* @var int
*/
private int $events_dropped = 0;
/**
* Number of invocations opened in this request.
*
* @var int
*/
private int $frames_opened = 0;
/**
* Constructor.
*/
public function __construct() {
add_action( 'init', array( $this, 'handle_init' ) );
}
/**
* Attach the tracking hooks when the store allows usage tracking, or on multisite.
*
* Consent is per site and a request can switch sites, so on multisite the hooks are always attached and consent is
* checked for each call instead.
*
* @internal
*/
public function handle_init(): void {
if ( ! is_multisite() && ! self::is_tracking_allowed() ) {
return;
}
add_action( 'wp_ability_invoked', array( $this, 'handle_wp_ability_invoked' ) );
add_filter( 'wp_ability_normalize_input', array( $this, 'handle_wp_ability_normalize_input' ), PHP_INT_MAX, 2 );
add_filter( 'wp_pre_execute_ability', array( $this, 'handle_wp_pre_execute_ability' ), PHP_INT_MAX, 2 );
add_filter( 'wp_ability_validate_input', array( $this, 'handle_wp_ability_validate_input' ), PHP_INT_MAX, 3 );
add_filter( 'wp_ability_permission_result', array( $this, 'handle_wp_ability_permission_result' ), PHP_INT_MAX, 2 );
add_action( 'wp_before_execute_ability', array( $this, 'handle_wp_before_execute_ability' ) );
add_filter( 'wp_ability_execute_result', array( $this, 'handle_wp_ability_execute_result' ), PHP_INT_MAX, 2 );
add_filter( 'wp_ability_validate_output', array( $this, 'handle_wp_ability_validate_output' ), PHP_INT_MAX, 3 );
add_action( 'wp_after_execute_ability', array( $this, 'handle_wp_after_execute_ability' ), 10, 2 );
add_filter( 'mcp_adapter_pre_tool_call', array( $this, 'handle_mcp_adapter_pre_tool_call' ) );
add_filter( 'rest_request_before_callbacks', array( $this, 'handle_rest_request_before_callbacks' ), 10, 3 );
add_filter( 'rest_request_after_callbacks', array( $this, 'handle_rest_request_after_callbacks' ), 10, 3 );
// Last, so ability calls made by other shutdown handlers are recorded too.
add_action( 'shutdown', array( $this, 'handle_shutdown' ), PHP_INT_MAX );
}
/**
* Handle the wp_ability_invoked action (WordPress 7.1+), which fires for every call.
*
* @internal
*
* @param string $ability_name The ability name.
*/
public function handle_wp_ability_invoked( $ability_name ): void {
if ( self::is_tracked_ability( $ability_name ) ) {
$this->open_frame( $ability_name, false );
}
}
/**
* Handle the wp_ability_normalize_input filter (WordPress 7.1+), to record a rejected normalization.
*
* A missing input schema never reaches this filter. That failure stays unclosed and is recorded as unknown.
*
* @internal
*
* @param mixed $input The normalized input, or a WP_Error when a filter rejected it. Not recorded.
* @param string $ability_name The ability name.
* @return mixed The unchanged value.
*/
public function handle_wp_ability_normalize_input( $input, $ability_name ) {
if ( is_wp_error( $input ) ) {
$this->close_frame( $ability_name, false, $input );
}
return $input;
}
/**
* Handle the wp_pre_execute_ability filter (WordPress 7.1+), to record short-circuited calls.
*
* @internal
*
* @param mixed $pre The pre-computed result, or the core sentinel to continue execution.
* @param string $ability_name The ability name.
* @return mixed The unchanged value.
*/
public function handle_wp_pre_execute_ability( $pre, $ability_name ) {
// WP_Filter_Sentinel ships with WordPress 7.1, which the PHPStan WordPress stubs predate (see #69841).
if ( ! $pre instanceof \WP_Filter_Sentinel ) { // @phpstan-ignore class.notFound
$this->close_frame( $ability_name, false, $pre );
}
return $pre;
}
/**
* Handle the wp_ability_validate_input filter (WordPress 7.1+), to record invalid input.
*
* @internal
*
* @param mixed $is_valid True, or false or a WP_Error when the input is invalid.
* @param mixed $input The input. Not recorded.
* @param string $ability_name The ability name.
* @return mixed The unchanged value.
*/
public function handle_wp_ability_validate_input( $is_valid, $input, $ability_name ) {
unset( $input );
$error = self::get_validation_error( $is_valid, 'ability_invalid_input' );
if ( $error ) {
$this->close_frame( $ability_name, false, $error );
}
return $is_valid;
}
/**
* Handle the wp_ability_permission_result filter (WordPress 7.1+), to record permission denials.
*
* @internal
*
* @param mixed $permission True when the call is allowed.
* @param string $ability_name The ability name.
* @return mixed The unchanged value.
*/
public function handle_wp_ability_permission_result( $permission, $ability_name ) {
if ( true !== $permission ) {
// Matches the error WP_Ability::execute() returns for denied calls.
$error = new WP_Error( 'ability_invalid_permissions' );
// The MCP Adapter checks permission before executing and never runs a refused call, so no frame is open.
// Only a tool call counts: other permission checks in the same request aren't refused calls.
if ( self::is_tracked_ability( $ability_name ) && null === $this->find_frame( $ability_name, false ) && $this->is_json_rpc_tool_call() ) {
$this->add_event( $this->create_frame( $ability_name, false ), $error, false );
++$this->frames_opened;
} else {
$this->close_frame( $ability_name, false, $error );
}
}
return $permission;
}
/**
* Handle the wp_before_execute_ability action.
*
* @internal
*
* @param string $ability_name The ability name.
*/
public function handle_wp_before_execute_ability( $ability_name ): void {
if ( ! self::is_tracked_ability( $ability_name ) ) {
return;
}
$index = $this->find_frame( $ability_name, false );
if ( null !== $index ) {
// Opened by wp_ability_invoked; time only the execution so durations match on WordPress 7.0.
$frame = $this->frames[ $index ];
$frame['executing'] = true;
$frame['start'] = microtime( true );
$this->frames[ $index ] = $frame;
return;
}
$this->open_frame( $ability_name, true );
}
/**
* Handle the wp_ability_execute_result filter (WordPress 7.1+), to record execution errors.
*
* @internal
*
* @param mixed $result The execution result. Not recorded.
* @param string $ability_name The ability name.
* @return mixed The unchanged value.
*/
public function handle_wp_ability_execute_result( $result, $ability_name ) {
if ( is_wp_error( $result ) ) {
$this->close_frame( $ability_name, true, $result );
}
return $result;
}
/**
* Handle the wp_ability_validate_output filter (WordPress 7.1+), to record invalid output.
*
* @internal
*
* @param mixed $is_valid True, or false or a WP_Error when the output is invalid.
* @param mixed $output The output. Not recorded.
* @param string $ability_name The ability name.
* @return mixed The unchanged value.
*/
public function handle_wp_ability_validate_output( $is_valid, $output, $ability_name ) {
unset( $output );
$error = self::get_validation_error( $is_valid, 'ability_invalid_output' );
if ( $error ) {
$this->close_frame( $ability_name, true, $error );
}
return $is_valid;
}
/**
* Handle the wp_after_execute_ability action, which fires after a successful execution.
*
* @internal
*
* @param string $ability_name The ability name.
* @param mixed $input The input. Only read for MCP Adapter discovery.
*/
public function handle_wp_after_execute_ability( $ability_name, $input = null ): void {
$this->close_frame( $ability_name, true, null );
$this->record_discovery( $ability_name, $input );
}
/**
* Handle the mcp_adapter_pre_tool_call filter, to mark the request as an MCP request.
*
* Covers MCP Adapter transports without MCP HTTP headers, such as STDIO.
*
* @internal
*
* @param mixed $args The tool arguments.
* @return mixed The unchanged arguments.
*/
public function handle_mcp_adapter_pre_tool_call( $args ) {
$this->is_mcp_request = true;
return $args;
}
/**
* Handle the rest_request_before_callbacks filter, to know which REST routes are being dispatched.
*
* @internal
*
* @param mixed $response The response, or null to continue dispatching.
* @param mixed $handler The route handler.
* @param mixed $request The request.
* @return mixed The unchanged response.
*/
public function handle_rest_request_before_callbacks( $response, $handler, $request ) {
unset( $handler );
if ( $request instanceof WP_REST_Request ) {
$this->rest_requests[] = $request;
$this->rest_frames_opened[] = $this->frames_opened;
}
return $response;
}
/**
* Handle the rest_request_after_callbacks filter.
*
* Also records run requests that the Abilities API rejected before execution, for example on permission checks.
*
* @internal
*
* @param mixed $response The response.
* @param mixed $handler The route handler.
* @param mixed $request The request.
* @return mixed The unchanged response.
*/
public function handle_rest_request_after_callbacks( $response, $handler, $request ) {
unset( $handler );
if ( ! $request instanceof WP_REST_Request ) {
return $response;
}
$frames_opened_before = (int) array_pop( $this->rest_frames_opened );
$ability_name = $request['name'];
if (
is_wp_error( $response )
// Abilities not exposed to REST look like unknown routes to callers; probing them isn't ability usage.
&& 'rest_ability_not_found' !== $response->get_error_code()
&& $this->frames_opened === $frames_opened_before
&& 1 === preg_match( self::ABILITIES_RUN_ROUTE_REGEX, $request->get_route() )
&& self::is_tracked_ability( $ability_name )
&& wp_has_ability( $ability_name )
&& self::is_tracking_allowed()
) {
$this->add_event( $this->create_frame( $ability_name, false ), $response, false );
}
array_pop( $this->rest_requests );
return $response;
}
/**
* Handle the shutdown action: record calls that never finished, then send the queued events.
*
* @internal
*/
public function handle_shutdown(): void {
while ( $this->frames ) {
$this->add_event( array_pop( $this->frames ), null, false );
}
if ( ! $this->events ) {
return;
}
$this->flush_events();
// This runs after WC_Tracks_Client's own send at priority 20, so the queued pixels are sent here.
try {
$this->send_queued_pixels();
} catch ( \Throwable $e ) {
unset( $e );
}
}
/**
* Queue one event in the batched Tracks client, which sends queued events on shutdown.
*
* @param array<string, mixed> $properties All Tracks properties of the event.
*/
protected function send_event( array $properties ): void {
$user = wp_get_current_user();
// WC_Tracks::record_event() skips the test suite, whose users use the wptests_ table prefix.
if ( $user instanceof \WP_User && 'wptests_capabilities' === $user->cap_key ) {
return;
}
\WC_Tracks_Client::record_event_batched( $properties );
}
/**
* Send the pixels queued in the batched Tracks client now.
*/
protected function send_queued_pixels(): void {
\WC_Tracks_Client::send_batched_pixels();
}
/**
* Whether this process can outlive many requests' worth of calls, such as an MCP STDIO server run with WP-CLI.
*
* @return bool
*/
protected function is_long_running_process(): bool {
return defined( 'WP_CLI' ) && WP_CLI;
}
/**
* Hand the recorded events to the Tracks client.
*/
private function flush_events(): void {
// Runs on shutdown, where an exception would also stop later shutdown callbacks.
try {
$last = array_key_last( $this->events );
if ( null !== $last && $this->events_dropped > 0 ) {
$this->events[ $last ]['events_dropped'] = $this->events_dropped;
$this->events_dropped = 0;
}
$events = $this->events;
$this->events = array();
} catch ( \Throwable $e ) {
unset( $e );
return;
}
foreach ( $events as $properties ) {
try {
$this->send_event( $properties );
} catch ( \Throwable $e ) {
unset( $e );
}
}
}
/**
* Start tracking an invocation.
*
* @param string $ability_name The ability name.
* @param bool $executing Whether execution already started (WordPress 7.0 path).
*/
private function open_frame( string $ability_name, bool $executing ): void {
// Consent is per site, and the site can change mid-request with switch_to_blog().
if ( ! self::is_tracking_allowed() ) {
return;
}
// Only agent entry points. Direct PHP and cron calls are plugin internals and could add a pixel to every page view.
if ( ! in_array( $this->get_channel(), self::TRACKED_CHANNELS, true ) ) {
return;
}
// Calls that fail without a closing hook keep their frame until shutdown. Recording the oldest one as an
// unknown failure keeps the stack bounded and lets later closing hooks still find their own frame.
if ( count( $this->frames ) >= self::MAX_EVENTS_PER_REQUEST ) {
$oldest = $this->frames[0];
array_shift( $this->frames );
$this->add_event( $oldest, null, false );
}
$this->frames[] = $this->create_frame( $ability_name, $executing );
++$this->frames_opened;
}
/**
* Create the record of an invocation, with the context it started in.
*
* @param string $ability_name The ability name.
* @param bool $executing Whether execution already started.
* @return array{name: string, channel: string, rest_namespace: string, external_client: string, start: float, executing: bool}
*/
private function create_frame( string $ability_name, bool $executing ): array {
$channel = $this->get_channel();
return array(
'name' => $ability_name,
'channel' => $channel,
'rest_namespace' => $this->get_rest_namespace(),
// Resolved now: the request metadata it reads is gone once the REST request finishes.
'external_client' => 'mcp' === $channel ? $this->get_external_client() : self::NONE,
'start' => microtime( true ),
'executing' => $executing,
);
}
/**
* Finish tracking the innermost open invocation of an ability.
*
* Invocations opened after it are calls that failed without a closing hook. On WordPress 7.0, a failed recursive
* call of the same ability can't be told apart from the outer call, so their outcomes can swap; counts stay right.
*
* @param mixed $ability_name The ability name.
* @param bool $executing Execution state the invocation must be in; hooks before and after execution share filters with other callers.
* @param mixed $result Null for success, a WP_Error for failure, or a short-circuited result.
*/
private function close_frame( $ability_name, bool $executing, $result ): void {
if ( ! self::is_tracked_ability( $ability_name ) ) {
return;
}
$index = $this->find_frame( $ability_name, $executing );
if ( null === $index ) {
return;
}
$frame = $this->frames[ $index ];
foreach ( array_splice( $this->frames, $index ) as $offset => $closed_frame ) {
if ( $offset > 0 ) {
$this->add_event( $closed_frame, null, false );
}
}
// Only executed calls report a duration, so it always measures execution.
$this->add_event( $frame, is_wp_error( $result ) ? $result : true, $frame['executing'] );
}
/**
* Find the innermost open invocation of an ability in a given execution state.
*
* Matching the state keeps a recursive call that failed without a closing hook from hiding its outer call.
*
* @param string $ability_name The ability name.
* @param bool $executing Whether the invocation must have started executing.
* @return int|null Index in the frames stack, or null when none is open.
*/
private function find_frame( string $ability_name, bool $executing ): ?int {
for ( $index = count( $this->frames ) - 1; $index >= 0; $index-- ) {
if ( $ability_name === $this->frames[ $index ]['name'] && $executing === $this->frames[ $index ]['executing'] ) {
return $index;
}
}
return null;
}
/**
* Queue a finished invocation as an ability_called event.
*
* @param array{name: string, channel: string, rest_namespace: string, external_client: string, start: float, executing: bool} $frame The invocation.
* @param true|WP_Error|null $outcome True for success, a WP_Error for a known failure, null for an unknown failure.
* @param bool $has_duration Whether the duration is known.
*/
private function add_event( array $frame, $outcome, bool $has_duration ): void {
$error_code = self::NONE;
if ( $outcome instanceof WP_Error ) {
$error_code = self::get_error_code( $outcome );
} elseif ( null === $outcome ) {
$error_code = 'unknown';
}
$event = array(
'ability_name' => self::get_event_ability_name( $frame['name'] ),
'outcome' => true === $outcome ? 'success' : 'error',
'error_code' => $error_code,
'channel' => $frame['channel'],
'rest_namespace' => $frame['rest_namespace'],
'external_client' => $frame['external_client'],
);
if ( $has_duration ) {
$event['duration_ms'] = (int) round( ( microtime( true ) - $frame['start'] ) * 1000 );
}
// Unknown failures are recorded later than the call (WordPress 7.0 has no hook for them), so they keep the call's
// start time. Site and user are still read now; they differ only if the request switched them since.
$this->queue_event( self::EVENT_NAME, $event, null === $outcome ? $frame['start'] : null );
}
/**
* Record an agent looking up abilities through the MCP Adapter: `get-ability-info` for a tracked ability, or
* `discover-abilities`. A separate event, so ability_called stays one row per call. Successful lookups only.
*
* @param mixed $ability_name The ability that ran.
* @param mixed $input Its input.
*/
private function record_discovery( $ability_name, $input ): void {
if ( 'mcp-adapter/discover-abilities' === $ability_name ) {
$looked_up = null;
} elseif ( 'mcp-adapter/get-ability-info' === $ability_name && is_array( $input ) && self::is_tracked_ability( $input['ability_name'] ?? null ) && wp_has_ability( $input['ability_name'] ) ) {
$looked_up = $input['ability_name'];
} else {
return;
}
$channel = $this->get_channel();
if ( ! in_array( $channel, self::TRACKED_CHANNELS, true ) ) {
return;
}
$this->queue_event(
self::DISCOVERY_EVENT_NAME,
array(
'ability_name' => null === $looked_up ? self::NONE : self::get_event_ability_name( $looked_up ),
'discovery' => null === $looked_up ? 'list' : 'info',
'channel' => $channel,
'external_client' => 'mcp' === $channel ? $this->get_external_client() : self::NONE,
)
);
}
/**
* Add the properties every event carries and queue the event for sending.
*
* Properties are built now, so the user, site and time are those of the call rather than of shutdown.
*
* @param string $event_name Event name, without the `wcadmin_` prefix.
* @param array<string, mixed> $event Event-specific properties.
* @param float|null $started microtime() to record as the event time, or null for now.
*/
private function queue_event( string $event_name, array $event, ?float $started = null ): void {
// Telemetry must never break the ability call: this runs third-party filters and Jetpack code inside core's hooks.
try {
if ( count( $this->events ) >= self::MAX_EVENTS_PER_REQUEST ) {
if ( ! $this->is_long_running_process() ) {
++$this->events_dropped;
return;
}
$this->flush_events();
$this->send_queued_pixels();
}
// The call itself may have turned tracking off.
if ( ! self::is_tracking_allowed() ) {
return;
}
// Web requests from logged-out visitors aren't merchant or agent usage, and anyone could trigger them.
$auth = self::get_auth_method();
if ( 'none' === $auth && ! ( defined( 'WP_CLI' ) && WP_CLI ) && ! wp_doing_cron() ) {
return;
}
$event['auth'] = $auth;
// Many local installs (localhost, .local, .test, DDEV, Lando) still report production.
$event['is_test'] = ( 'production' !== wp_get_environment_type() || ( class_exists( Status::class ) && ( new Status() )->is_local_site() ) ) ? 'true' : 'false';
$event['is_a11n'] = self::is_a11n() ? 'true' : 'false';
$properties = \WC_Tracks::get_properties( \WC_Tracks::PREFIX . $event_name, $event );
// The request URL and referrer can carry ability input, e.g. in the query string of GET run requests.
unset( $properties['_dl'], $properties['_dr'] );
if ( null !== $started ) {
$properties['_ts'] = number_format( round( $started * 1000 ), 0, '', '' );
}
$this->events[] = $properties;
} catch ( \Throwable $e ) {
unset( $e );
}
}
/**
* Ability name as recorded: the `/` becomes `__`, and hyphens stay, so `products-query` and `products_query` stay
* different events.
*
* @param string $ability_name Ability name.
* @return string
*/
private static function get_event_ability_name( string $ability_name ): string {
return implode( '__', explode( '/', strtolower( $ability_name ), 2 ) );
}
/**
* Identify how the ability was invoked.
*
* @return string
*/
private function get_channel(): string {
if ( $this->is_mcp_request() ) {
return 'mcp';
}
foreach ( $this->rest_requests as $request ) {
if ( 1 === preg_match( self::ABILITIES_RUN_ROUTE_REGEX, $request->get_route() ) ) {
return 'rest';
}
}
// Before WP-CLI: `wp cron event run` defines DOING_CRON, and that is scheduled work, not an agent.
if ( wp_doing_cron() ) {
return 'cron';
}
if ( defined( 'WP_CLI' ) && WP_CLI ) {
return 'cli';
}
return 'other';
}
/**
* Whether this is an MCP request.
*
* MCP Streamable HTTP clients send MCP-Protocol-Version on every request after initialization (2025-06-18 and
* later) and Mcp-Session-Id when the server assigned a session, whichever server implementation handles them.
*
* @return bool
*/
private function is_mcp_request(): bool {
if ( null === $this->is_mcp_request ) {
$this->is_mcp_request = isset( $_SERVER['HTTP_MCP_PROTOCOL_VERSION'] ) || isset( $_SERVER['HTTP_MCP_SESSION_ID'] );
}
return $this->is_mcp_request || $this->is_json_rpc_tool_call();
}
/**
* Whether the outermost REST request is a JSON-RPC `tools/call`, as every MCP tool call over HTTP is, including from
* 2025-03-26 clients that send no MCP headers. Batches (2025-03-26) are checked message by message.
*
* @return bool
*/
private function is_json_rpc_tool_call(): bool {
$request = $this->rest_requests[0] ?? null;
$body = $request ? $request->get_json_params() : null;
if ( ! is_array( $body ) ) {
return false;
}
foreach ( isset( $body['jsonrpc'] ) ? array( $body ) : $body as $message ) {
if ( is_array( $message ) && '2.0' === ( $message['jsonrpc'] ?? null ) && 'tools/call' === ( $message['method'] ?? null ) ) {
return true;
}
}
return false;
}
/**
* Get the namespace of the outermost REST route being dispatched, such as `wp_abilities` or `mcp`.
*
* Only the namespace is used: the rest of the route can hold IDs.
*
* @return string
*/
private function get_rest_namespace(): string {
if ( ! $this->rest_requests ) {
return self::NONE;
}
$segments = explode( '/', ltrim( $this->rest_requests[0]->get_route(), '/' ), 2 );
return self::normalize_value( $segments[0] );
}
/**
* Get the error code to record for an error.
*
* Codes are normally fixed slugs, but any filter can return an error whose code was built from input, so codes
* that don't look like slugs are recorded as `other`.
*
* @param WP_Error $error The error.
* @return string
*/
private static function get_error_code( WP_Error $error ): string {
$code = (string) $error->get_error_code();
return 1 === preg_match( '/^[A-Za-z0-9_-]{1,64}$/', $code ) ? self::normalize_value( $code ) : 'other';
}
/**
* Get the error a validation filter result stands for, matching how WP_Ability treats it.
*
* @param mixed $is_valid The filtered validation result.
* @param string $default_code Error code to use when the result is false.
* @return WP_Error|null The error, or null when the value is valid.
*/
private static function get_validation_error( $is_valid, string $default_code ): ?WP_Error {
if ( false === $is_valid ) {
return new WP_Error( $default_code );
}
return is_wp_error( $is_valid ) && $is_valid->has_errors() ? $is_valid : null;
}
/**
* Identify how the caller authenticated, so agents can be told apart from people in wp-admin.
*
* @return string `application_password`, `jetpack`, `cookie`, `other` (another REST authentication method) or
* `none` (logged out, WP-CLI or cron).
*/
private static function get_auth_method(): string {
if ( function_exists( 'rest_get_authenticated_app_password' ) && rest_get_authenticated_app_password() ) {
return 'application_password';
}
if ( self::is_jetpack_signed_request() ) {
return 'jetpack';
}
if ( ! is_user_logged_in() || ( defined( 'WP_CLI' ) && WP_CLI ) || wp_doing_cron() ) {
return 'none';
}
if ( wp_is_serving_rest_request() ) {
global $wp_rest_auth_cookie;
return true === $wp_rest_auth_cookie ? 'cookie' : 'other';
}
return 'cookie';
}
/**
* Whether Jetpack authenticated this request with a blog or user token signature.
*
* Jetpack is only asked when the request carries its signature arguments, so its REST authentication isn't
* initialized here on other requests.
*
* @return bool
*/
private static function is_jetpack_signed_request(): bool {
// phpcs:ignore WordPress.Security.NonceVerification.Recommended -- Only checks for the presence of Jetpack's signature arguments.
if ( ! isset( $_GET['token'], $_GET['signature'] ) ) {
return false;
}
$rest_authentication = 'Automattic\Jetpack\Connection\Rest_Authentication';
return is_callable( array( $rest_authentication, 'is_signed_with_blog_token' ) )
&& is_callable( array( $rest_authentication, 'is_signed_with_user_token' ) )
&& ( $rest_authentication::is_signed_with_blog_token() || $rest_authentication::is_signed_with_user_token() );
}
/**
* Whether an Automattician made the call: signed in on WordPress.com, or through the Automattic proxy.
*
* Only detectable on WordPress.com and Atomic; always false elsewhere.
*
* @return bool
*/
private static function is_a11n(): bool {
if ( function_exists( 'is_automattician' ) && is_automattician() ) {
return true;
}
if ( defined( 'AT_PROXIED_REQUEST' ) && AT_PROXIED_REQUEST ) {
return true;
}
if ( function_exists( 'wpcom_is_proxied_request' ) ) {
return (bool) wpcom_is_proxied_request();
}
if ( isset( $_SERVER['A8C_PROXIED_REQUEST'] ) && is_string( $_SERVER['A8C_PROXIED_REQUEST'] ) ) {
return '1' === sanitize_text_field( wp_unslash( $_SERVER['A8C_PROXIED_REQUEST'] ) );
}
return defined( 'A8C_PROXIED_REQUEST' ) && A8C_PROXIED_REQUEST;
}
/**
* Whether the current site allows usage tracking.
*
* Unlike WC_Site_Tracking::is_tracking_enabled() alone, this requires the stored opt-in: that method also treats a
* posted `wc_tracker_checkbox=yes` (the onboarding opt-in) as consent, and any visitor can post to the REST API.
*
* @return bool
*/
private static function is_tracking_allowed(): bool {
try {
return 'yes' === get_option( 'woocommerce_allow_tracking' ) && \WC_Site_Tracking::is_tracking_enabled();
} catch ( \Throwable $e ) {
// The consent filters are third-party code; a failure there must not break the ability call.
return false;
}
}
/**
* Whether an ability is in the tracked namespace.
*
* @param mixed $ability_name The ability name.
* @return bool
*/
private static function is_tracked_ability( $ability_name ): bool {
return is_string( $ability_name ) && 0 === strpos( $ability_name, self::ABILITY_PREFIX );
}
/**
* Get the MCP client, as one of the known clients, `other` or `none`.
*
* The client supplies its own name, so only known clients are recorded by name.
*
* @return string
*/
private function get_external_client(): string {
try {
return $this->resolve_external_client();
} catch ( \Throwable $e ) {
// The session lookup is MCP Adapter code; a failure there must not break the ability call.
return self::NONE;
}
}
/**
* Resolve and cache the MCP client.
*
* @return string
*/
private function resolve_external_client(): string {
if ( null === $this->external_client ) {
$name = $this->get_mcp_client_name_from_request() ?? self::get_mcp_client_name_from_session();
if ( null === $name ) {
$this->external_client = self::NONE;
} else {
$this->external_client = 'other';
$tokens = '_' . self::normalize_value( $name ) . '_';
foreach ( self::KNOWN_MCP_CLIENTS as $needle => $client ) {
if ( false !== strpos( $tokens, '_' . $needle . '_' ) ) {
$this->external_client = $client;
break;
}
}
}
}
return $this->external_client;
}
/**
* Get the MCP client name from the request metadata, which MCP 2026-07-28 sends with every request.
*
* @return string|null
*/
private function get_mcp_client_name_from_request(): ?string {
$request = $this->rest_requests[0] ?? null;
$message = $request ? $request->get_json_params() : null;
$name = is_array( $message ) ? ( $message['params']['_meta']['io.modelcontextprotocol/clientInfo']['name'] ?? null ) : null;
return is_string( $name ) ? $name : null;
}
/**
* Get the MCP client name from the MCP Adapter session (MCP 2025-11-25 and earlier).
*
* @return string|null
*/
private static function get_mcp_client_name_from_session(): ?string {
$session_manager = array( 'WP\MCP\Transport\Infrastructure\SessionManager', 'get_session' );
$session_id = isset( $_SERVER['HTTP_MCP_SESSION_ID'] ) && is_string( $_SERVER['HTTP_MCP_SESSION_ID'] ) ? sanitize_text_field( wp_unslash( $_SERVER['HTTP_MCP_SESSION_ID'] ) ) : '';
if ( '' === $session_id || ! get_current_user_id() || ! is_callable( $session_manager ) ) {
return null;
}
$session = call_user_func( $session_manager, get_current_user_id(), $session_id );
$name = is_array( $session ) ? ( $session['client_params']['clientInfo']['name'] ?? null ) : null;
return is_string( $name ) ? $name : null;
}
/**
* Convert a value to lowercase words separated by underscores, as Tracks property values expect.
*
* @param string $value The value.
* @param int|null $max_length Maximum length, or null for no limit.
* @return string The normalized value, or 'none' when nothing is left.
*/
private static function normalize_value( string $value, ?int $max_length = 64 ): string {
$value = trim( (string) preg_replace( '/[^a-z0-9]+/', '_', strtolower( $value ) ), '_' );
if ( '' === $value ) {
return self::NONE;
}
return null === $max_length ? $value : (string) substr( $value, 0, $max_length );
}
}