From c94ce2ce323107fa0cc9a0b2efd1045a08089c15 Mon Sep 17 00:00:00 2001 From: Jake Spurlock Date: Fri, 6 Nov 2026 18:05:54 -0800 Subject: [PATCH 1/8] feat(ai-workspace): let the assistant read basic site info Part of #1287 (PR B, U6). In a live run of #1314 the assistant proposed a new tagline and site title without being able to read the current ones. ai/get-site-info returns the site's name, tagline, home URL, language, timezone, date and time formats, active theme and whether it is a block theme, plus the WordPress and PHP versions for users with manage_options. It never returns the admin email, database details or the plugin list. - A read ability like the content reads: any logged-in user, annotated read-only and not open-world, listed over MCP. It joins the workspace's curated tool list, since policy admission is off by default. - core/get-site-info joins NEVER_ADMITTED next to the environment and settings readers, because it returns the admin email. - Ports the field choices from #1214's Read_Site, without its posts, pages and plugins sections. Co-authored-by: Vrishabhsk Co-Authored-By: Claude Opus 5.5 --- docs/experiments/ai-workspace.md | 12 + includes/Abilities/Site/Get_Site_Info.php | 206 ++++++++++++ .../Experiments/AI_Workspace/AI_Workspace.php | 8 + .../Experiments/AI_Workspace/Tool_Policy.php | 7 + .../AI_Workspace/Tool_Selector.php | 5 + readme.txt | 1 + .../Abilities/Site/Get_Site_InfoTest.php | 315 ++++++++++++++++++ .../AI_Workspace/Tool_PolicyTest.php | 39 +++ .../AI_Workspace/Tool_SelectorTest.php | 9 +- 9 files changed, 599 insertions(+), 3 deletions(-) create mode 100644 includes/Abilities/Site/Get_Site_Info.php create mode 100644 tests/Integration/Includes/Abilities/Site/Get_Site_InfoTest.php diff --git a/docs/experiments/ai-workspace.md b/docs/experiments/ai-workspace.md index 72fa63c60..e4bf3a370 100644 --- a/docs/experiments/ai-workspace.md +++ b/docs/experiments/ai-workspace.md @@ -54,6 +54,7 @@ The abilities offered to the model are not everything registered on the site. Th | `ai/search-content` | Full-text search over the post types exposed to abilities, or the newest posts when there is no search term, filterable by term, date range and featured image; returns titles, excerpts and terms | any authenticated user | | `ai/read-content-bodies` | Returns the full body text of up to five posts named by ID | any authenticated user | | `ai/list-terms` | Lists the site's categories, tags and other public terms with how many published posts each holds | any authenticated user | +| `ai/get-site-info` | Returns the site's name, tagline, home URL, language, timezone, date and time formats and active theme, with the WordPress and PHP versions for `manage_options` only | any authenticated user | | `ai/propose-drafts` | Records a proposed set of drafts for a person to approve; writes nothing | `edit_posts` | | `ai/propose-template` | Records one proposed block template for a person to approve; writes nothing | `edit_theme_options` | | `ai/ask-user` | Asks the person one question with two to five choices, which ends the turn until they answer; writes nothing | any authenticated user (the ability itself requires `manage_options`) | @@ -184,6 +185,12 @@ Two properties are worth stating plainly: Registered alongside `ai/search-content`. It lists the terms of publicly viewable taxonomies attached to a post type exposed to abilities, with each term's `name`, `slug` and published-post `count`. With no `taxonomy` it lists categories and tags. `orderby` is `name` (the default) or `count` (most posts first), `hide_empty` defaults to true, and `per_page` is capped at 100; `total` says how many terms match in all. Term names and counts are already public, so it needs only an authenticated user. It stays until `core/terms-query` ([#1099](https://github.com/WordPress/ai/pull/1099), [#1084](https://github.com/WordPress/ai/pull/1084)) lands in this plugin. +### `ai/get-site-info` + +Registered alongside `ai/search-content`, shown in REST, and listed over MCP by the MCP Adapter experiment like the other reads. It takes no input and returns a fixed set of fields: `name`, `tagline`, `home_url`, `language` (the site locale, such as `en_US`), `timezone` (a named zone, or a UTC offset such as `-05:00` when none is set), `date_format`, `time_format`, `theme` (the active theme's name) and `is_block_theme`. A user who can `manage_options` also gets `wp_version` and `php_version`; the output schema marks both optional, and an editor's response leaves them out rather than sending them empty. It needs only an authenticated user, like the other reads, because every other field is visible on the front end. + +It never returns the admin email, the WordPress address (`siteurl`), database details or the plugin list. That is why it sits on the floor while `core/get-environment-info` and `core/settings-get` stay on the [withheld list](#wpai_workspace_withheld_abilities): two version strings for administrators are a narrow exception to that list's rationale, not a way around it. It is annotated read-only, not destructive, idempotent and not open-world, so it stays admissible if declaration-based admission is switched on. + ### `ai/read-content-bodies` The reading half of retrieval, and the largest increase in reachable content on this surface. Registered by this experiment for the same reason the search ability is: `core/content-query` belongs to the Custom Abilities experiment, and the workspace's reach must not change when a different experiment is switched off. @@ -473,6 +480,11 @@ and `core/get-user-info` is already public, read-only and not destructive -- the only thing keeping it off the surface is an absent `open_world` hint, which it would be correct for core to add. +The plugin's own `ai/get-site-info` is not on this list, although it reads +site configuration: it returns a fixed field set with no admin email, no plugin +list and no database details, and the WordPress and PHP versions only for +`manage_options`. + Removing one is a deliberate act by someone with code access, which is the point: diff --git a/includes/Abilities/Site/Get_Site_Info.php b/includes/Abilities/Site/Get_Site_Info.php new file mode 100644 index 000000000..b9cc8079e --- /dev/null +++ b/includes/Abilities/Site/Get_Site_Info.php @@ -0,0 +1,206 @@ + __( 'Get Site Info', 'ai' ), + 'description' => __( 'Returns facts about this site: its name, tagline, home URL, language, timezone, date and time formats, active theme and whether it is a block theme. The WordPress and PHP versions are included only for administrators. Takes no input. Requires an authenticated user.', 'ai' ), + 'category' => WPAI_DEFAULT_ABILITY_CATEGORY, + 'input_schema' => array( + 'type' => 'object', + 'additionalProperties' => false, + 'properties' => array(), + ), + 'output_schema' => $this->get_output_schema(), + 'execute_callback' => array( $this, 'execute_get_site_info' ), + 'permission_callback' => array( $this, 'check_permission' ), + 'meta' => array( + 'annotations' => array( + 'readonly' => true, + 'destructive' => false, + 'idempotent' => true, + // This ability only reads the local site. + 'open_world' => false, + ), + 'show_in_rest' => true, + ), + ) + ); + } + + /** + * Permission callback for the `ai/get-site-info` ability. + * + * @since x.x.x + * + * @param mixed $input Optional. The ability input. Default empty array. + * @return bool True if the request may proceed. + */ + public function check_permission( $input = array() ): bool { + unset( $input ); + + return is_user_logged_in(); + } + + /** + * Executes the `ai/get-site-info` ability. + * + * @since x.x.x + * + * @param mixed $input Optional. The ability input. Default empty array. + * @return array The site facts. + */ + public function execute_get_site_info( $input = array() ): array { + unset( $input ); + + $info = array( + 'name' => (string) get_bloginfo( 'name' ), + 'tagline' => (string) get_bloginfo( 'description' ), + 'home_url' => (string) home_url( '/' ), + 'language' => (string) get_locale(), + // A named zone, or the UTC offset such as `-05:00` when none is set. + 'timezone' => (string) wp_timezone_string(), + 'date_format' => (string) get_option( 'date_format' ), + 'time_format' => (string) get_option( 'time_format' ), + 'theme' => (string) wp_get_theme()->get( 'Name' ), + 'is_block_theme' => wp_is_block_theme(), + ); + + // Versions say which known vulnerabilities apply, so only administrators get them. + if ( current_user_can( 'manage_options' ) ) { + $info['wp_version'] = (string) get_bloginfo( 'version' ); + $info['php_version'] = PHP_VERSION; + } + + return $info; + } + + /** + * Builds the output schema for the `ai/get-site-info` ability. + * + * @since x.x.x + * + * @return array The output JSON Schema. + */ + private function get_output_schema(): array { + return array( + 'type' => 'object', + 'additionalProperties' => false, + 'required' => array( 'name', 'tagline', 'home_url', 'language', 'timezone', 'date_format', 'time_format', 'theme', 'is_block_theme' ), + 'properties' => array( + 'name' => array( + 'type' => 'string', + 'description' => __( 'The site title.', 'ai' ), + ), + 'tagline' => array( + 'type' => 'string', + 'description' => __( 'The site tagline, which may be empty.', 'ai' ), + ), + 'home_url' => array( + 'type' => 'string', + 'format' => 'uri', + 'description' => __( 'The address of the site\'s front page.', 'ai' ), + ), + 'language' => array( + 'type' => 'string', + 'description' => __( 'The site language, as a locale such as en_US.', 'ai' ), + ), + 'timezone' => array( + 'type' => 'string', + 'description' => __( 'The site timezone, as a named zone such as America/Denver or a UTC offset such as -05:00.', 'ai' ), + ), + 'date_format' => array( + 'type' => 'string', + 'description' => __( 'The site date format, in PHP date() notation.', 'ai' ), + ), + 'time_format' => array( + 'type' => 'string', + 'description' => __( 'The site time format, in PHP date() notation.', 'ai' ), + ), + 'theme' => array( + 'type' => 'string', + 'description' => __( 'The name of the active theme.', 'ai' ), + ), + 'is_block_theme' => array( + 'type' => 'boolean', + 'description' => __( 'Whether the active theme is a block theme.', 'ai' ), + ), + 'wp_version' => array( + 'type' => 'string', + 'description' => __( 'The WordPress version. Present only for administrators.', 'ai' ), + ), + 'php_version' => array( + 'type' => 'string', + 'description' => __( 'The PHP version. Present only for administrators.', 'ai' ), + ), + ), + ); + } +} diff --git a/includes/Experiments/AI_Workspace/AI_Workspace.php b/includes/Experiments/AI_Workspace/AI_Workspace.php index 9d087185a..bbbfc0a3d 100644 --- a/includes/Experiments/AI_Workspace/AI_Workspace.php +++ b/includes/Experiments/AI_Workspace/AI_Workspace.php @@ -13,6 +13,7 @@ use WordPress\AI\Abilities\Content\Read_Content_Bodies; use WordPress\AI\Abilities\Content\Search_Content; use WordPress\AI\Abilities\Show_In_Abilities; +use WordPress\AI\Abilities\Site\Get_Site_Info; use WordPress\AI\Abstracts\Abstract_Feature; use WordPress\AI\Asset_Loader; use WordPress\AI\Experiments\AI_Workspace\REST\Conversation_Controller; @@ -119,6 +120,13 @@ public function register(): void { */ ( new List_Terms() )->init(); + /* + * Facts about the site itself: name, tagline, language, timezone, formats + * and theme, with the WordPress and PHP versions for administrators only. + * Registered here for the same reason as search. + */ + ( new Get_Site_Info() )->init(); + /* * The model's reach toward the write path. It stores a proposal and * writes nothing; it is withheld from the REST and MCP surfaces because diff --git a/includes/Experiments/AI_Workspace/Tool_Policy.php b/includes/Experiments/AI_Workspace/Tool_Policy.php index 2dbc398dd..37dfb29b5 100644 --- a/includes/Experiments/AI_Workspace/Tool_Policy.php +++ b/includes/Experiments/AI_Workspace/Tool_Policy.php @@ -184,6 +184,12 @@ class Tool_Policy { * keeping it off the surface is an absent `open_world` hint, and * `open_world => false` would be a correct thing for core to add. * + * The plugin's own `ai/get-site-info` is on the curated floor despite + * reading site configuration, because it returns only a fixed field set: no + * admin email, no plugin list, no database details, and the WordPress and PHP + * versions only for a user who can `manage_options`. It is not the broad + * `core/get-environment-info`, `core/settings-get` or `core/get-site-info` (which returns the admin email) this list withholds. + * * @since x.x.x * * @var list @@ -195,6 +201,7 @@ class Tool_Policy { 'core/settings-get', 'core/read-settings', 'core/get-environment-info', + 'core/get-site-info', ); /** diff --git a/includes/Experiments/AI_Workspace/Tool_Selector.php b/includes/Experiments/AI_Workspace/Tool_Selector.php index 2d9037af7..bc90d42c7 100644 --- a/includes/Experiments/AI_Workspace/Tool_Selector.php +++ b/includes/Experiments/AI_Workspace/Tool_Selector.php @@ -202,6 +202,11 @@ public function __construct( ?Tool_Policy $policy = null, ?Proposal_Store $propo self::READ_ABILITY => '', // Term names and post counts are already public, like search results. 'ai/list-terms' => '', + /* + * The output is already filtered per user: the versions are added only + * for `manage_options`, and the rest is visible on the front end. + */ + 'ai/get-site-info' => '', ); /** diff --git a/readme.txt b/readme.txt index 1e4b06ff1..91786b860 100644 --- a/readme.txt +++ b/readme.txt @@ -233,6 +233,7 @@ Go to `Plugins` and deactivate AI. If you can't reach the admin, deactivate it w - New Experiment: AI Workspace; a dedicated `Tools -> AI Workspace` screen where you hold a multi-step, site-aware conversation with an assistant. The assistant can search your content under your own capabilities, renders post results as a table, and writes nothing until you approve a proposal, which shows the exact values -- including the post status -- that will be written ([#282](https://github.com/WordPress/ai/issues/282)). - New `ai/search-content` Ability that runs a bounded, capability-filtered full-text search across the post types exposed to abilities, returning titles and excerpts rather than post bodies ([#282](https://github.com/WordPress/ai/issues/282)). +- New `ai/get-site-info` Ability that returns the site's name, tagline, home URL, language, timezone, date and time formats, active theme and whether it is a block theme, plus the WordPress and PHP versions for users who can `manage_options`. It never returns the admin email, the WordPress address, database details or the plugin list, which is why the AI Workspace offers it while withholding the broad `core/get-environment-info` and `core/settings-get` ([#1287](https://github.com/WordPress/ai/issues/1287)). - The AI Workspace's tool surface is no longer a fixed list. An ability exposed to the surface - through `meta.public`, or by naming the `ai-workspace` channel - and annotated `readonly: true`, `destructive: false`, `open_world: false` - can be offered to the assistant alongside the three that ship with it. Admission defaults to refusing: an ability that is not public, and has not opted in, is never offered. Declaration-based admission is itself switched **off** until [#354](https://github.com/WordPress/ai/issues/354) settles the channel name, so the shipped surface is still the three curated abilities; `add_filter( 'wpai_workspace_tool_admission_enabled', '__return_true' )`, or the `WPAI_WORKSPACE_TOOL_ADMISSION` constant, turns it on to try it. A short list of core abilities that read personal data, settings or environment detail is never admitted whatever they declare, filterable through `wpai_workspace_withheld_abilities`. Exposure and the annotations are both the ability author's self-attestation, and the effect class is a declared intent rather than an enforced property: the site owner's Explorer controls and the execute-time `permission_callback` remain the boundaries ([#1003](https://github.com/WordPress/ai/issues/1003)). - The Abilities Explorer shows which abilities the AI Workspace assistant can call, the exact description text the model receives, and why any other ability is excluded. A site owner can remove an ability from the surface or switch the policy off entirely and return to the three that ship ([#1003](https://github.com/WordPress/ai/issues/1003)). diff --git a/tests/Integration/Includes/Abilities/Site/Get_Site_InfoTest.php b/tests/Integration/Includes/Abilities/Site/Get_Site_InfoTest.php new file mode 100644 index 000000000..c3499c4b9 --- /dev/null +++ b/tests/Integration/Includes/Abilities/Site/Get_Site_InfoTest.php @@ -0,0 +1,315 @@ + + */ + private const SHARED_FIELDS = array( // phpcs:ignore SlevomatCodingStandard.Classes.DisallowMultiConstantDefinition -- This is a single array constant. + 'name', + 'tagline', + 'home_url', + 'language', + 'timezone', + 'date_format', + 'time_format', + 'theme', + 'is_block_theme', + ); + + /** + * The fields only a user who can `manage_options` gets. + * + * @since x.x.x + * + * @var list + */ + private const VERSION_FIELDS = array( 'wp_version', 'php_version' ); // phpcs:ignore SlevomatCodingStandard.Classes.DisallowMultiConstantDefinition -- This is a single array constant. + + /** + * Shared user IDs keyed by role. + * + * @since x.x.x + * + * @var array + */ + private static $user_ids = array(); + + /** + * Creates the shared users. + * + * @since x.x.x + * + * @param \WP_UnitTest_Factory $factory The unit test factory. + */ + public static function wpSetUpBeforeClass( $factory ): void { + self::$user_ids = array( + 'administrator' => $factory->user->create( array( 'role' => 'administrator' ) ), + 'editor' => $factory->user->create( array( 'role' => 'editor' ) ), + 'subscriber' => $factory->user->create( array( 'role' => 'subscriber' ) ), + ); + } + + /** + * Set up test case. + * + * @since x.x.x + */ + public function setUp(): void { + parent::setUp(); + + update_option( 'blogname', 'Field Notes' ); + update_option( 'blogdescription', 'Notes from the field' ); + update_option( 'timezone_string', 'America/Denver' ); + update_option( 'date_format', 'j F Y' ); + update_option( 'time_format', 'H:i' ); + update_option( 'admin_email', 'owner-secret@example.org' ); + update_option( 'siteurl', home_url( '/wp-core-secret' ) ); + + $this->register_ability(); + } + + /** + * Tear down test case. + * + * @since x.x.x + */ + public function tearDown(): void { + remove_filter( 'wp_register_ability_args', array( Exposure_Overrides::class, 'filter_ability_args' ), 100 ); + + if ( wp_has_ability( Get_Site_Info::ABILITY ) ) { + wp_unregister_ability( Get_Site_Info::ABILITY ); + } + + wp_set_current_user( 0 ); + + parent::tearDown(); + } + + /** + * Registers the ability inside a faked `wp_abilities_api_init` action. + * + * @since x.x.x + */ + private function register_ability(): void { + global $wp_current_filter; + $wp_current_filter[] = 'wp_abilities_api_init'; // phpcs:ignore WordPress.WP.GlobalVariablesOverride.Prohibited -- Faking the action context to register within it. + try { + ( new Get_Site_Info() )->register(); + } finally { + array_pop( $wp_current_filter ); + } + } + + /** + * Runs the ability as a user with the given role. + * + * @since x.x.x + * + * @param string $role The role to run as. + * @return mixed The ability result. + */ + private function run_as( string $role ) { + wp_set_current_user( self::$user_ids[ $role ] ); + + return wp_get_ability( Get_Site_Info::ABILITY )->execute( array() ); + } + + /** + * An administrator gets every field, including the WordPress and PHP versions. + * + * @since x.x.x + */ + public function test_administrator_gets_every_field_including_versions(): void { + $result = $this->run_as( 'administrator' ); + + $this->assertIsArray( $result ); + $this->assertSame( array_merge( self::SHARED_FIELDS, self::VERSION_FIELDS ), array_keys( $result ) ); + $this->assertSame( 'Field Notes', $result['name'] ); + $this->assertSame( 'Notes from the field', $result['tagline'] ); + $this->assertSame( home_url( '/' ), $result['home_url'] ); + $this->assertSame( get_locale(), $result['language'] ); + $this->assertSame( 'America/Denver', $result['timezone'] ); + $this->assertSame( 'j F Y', $result['date_format'] ); + $this->assertSame( 'H:i', $result['time_format'] ); + $this->assertSame( wp_get_theme()->get( 'Name' ), $result['theme'] ); + $this->assertSame( wp_is_block_theme(), $result['is_block_theme'] ); + $this->assertSame( get_bloginfo( 'version' ), $result['wp_version'] ); + $this->assertSame( PHP_VERSION, $result['php_version'] ); + } + + /** + * A site set to a UTC offset rather than a named zone reports the offset. + * + * @since x.x.x + */ + public function test_timezone_falls_back_to_the_utc_offset(): void { + update_option( 'timezone_string', '' ); + update_option( 'gmt_offset', -5 ); + + $result = $this->run_as( 'editor' ); + + $this->assertSame( '-05:00', $result['timezone'] ); + } + + /** + * An editor gets the same fields without the versions. + * + * @since x.x.x + */ + public function test_editor_gets_the_fields_without_versions(): void { + $result = $this->run_as( 'editor' ); + + $this->assertIsArray( $result ); + $this->assertSame( self::SHARED_FIELDS, array_keys( $result ) ); + $this->assertSame( 'Field Notes', $result['name'] ); + $this->assertSame( 'Notes from the field', $result['tagline'] ); + $this->assertArrayNotHasKey( 'wp_version', $result ); + $this->assertArrayNotHasKey( 'php_version', $result ); + } + + /** + * No response carries the admin email, the WordPress address, the database version or plugin names. + * + * @since x.x.x + */ + public function test_no_response_carries_admin_email_siteurl_database_or_plugins(): void { + global $wpdb; + + $plugins = (array) get_option( 'active_plugins', array() ); + + foreach ( array( 'administrator', 'editor' ) as $role ) { + $encoded = (string) wp_json_encode( $this->run_as( $role ) ); + + $this->assertStringNotContainsString( 'owner-secret@example.org', $encoded, $role ); + $this->assertStringNotContainsString( 'wp-core-secret', $encoded, $role ); + $this->assertStringNotContainsString( (string) $wpdb->db_server_info(), $encoded, $role ); + $this->assertStringNotContainsString( 'db_version', $encoded, $role ); + $this->assertStringNotContainsString( 'plugin', $encoded, $role ); + + foreach ( $plugins as $plugin ) { + $this->assertStringNotContainsString( (string) wp_json_encode( (string) $plugin ), $encoded, $role ); + } + } + } + + /** + * A visitor who is not logged in is refused. + * + * @since x.x.x + */ + public function test_logged_out_visitor_is_refused(): void { + wp_set_current_user( 0 ); + + $this->assertWPError( wp_get_ability( Get_Site_Info::ABILITY )->execute( array() ) ); + } + + /** + * The output schema requires the shared fields and leaves the versions optional. + * + * @since x.x.x + */ + public function test_output_schema_marks_the_versions_optional(): void { + $schema = wp_get_ability( Get_Site_Info::ABILITY )->get_output_schema(); + + $this->assertSame( self::SHARED_FIELDS, $schema['required'] ); + $this->assertFalse( $schema['additionalProperties'] ); + + foreach ( self::VERSION_FIELDS as $field ) { + $this->assertArrayHasKey( $field, $schema['properties'] ); + $this->assertNotContains( $field, $schema['required'] ); + } + } + + /** + * Registration carries a category and the read-only, closed-world annotations. + * + * WordPress trunk refuses an ability without a registered category, so this + * also stands for "registers on trunk". + * + * @since x.x.x + */ + public function test_registration_has_a_category_and_read_only_annotations(): void { + $ability = wp_get_ability( Get_Site_Info::ABILITY ); + + $this->assertNotNull( $ability ); + $this->assertSame( WPAI_DEFAULT_ABILITY_CATEGORY, $ability->get_category() ); + $this->assertTrue( wp_has_ability_category( WPAI_DEFAULT_ABILITY_CATEGORY ) ); + + $meta = $ability->get_meta(); + + $this->assertTrue( $meta['annotations']['readonly'] ); + $this->assertFalse( $meta['annotations']['destructive'] ); + $this->assertTrue( $meta['annotations']['idempotent'] ); + $this->assertFalse( $meta['annotations']['open_world'] ); + $this->assertTrue( $meta['show_in_rest'] ); + } + + /** + * With policy admission off, as it ships, the ability is declared to the model for an administrator and an editor. + * + * @since x.x.x + */ + public function test_declared_to_the_model_for_administrator_and_editor_with_admission_off(): void { + $this->assertFalse( ( new Tool_Policy() )->admission_is_enabled(), 'Admission must be off, as it ships.' ); + + foreach ( array( 'administrator', 'editor' ) as $role ) { + wp_set_current_user( self::$user_ids[ $role ] ); + + $selector = new Tool_Selector(); + + $this->assertArrayHasKey( Get_Site_Info::ABILITY, $selector->get_candidates() ); + $this->assertSame( '', $selector->get_candidates()[ Get_Site_Info::ABILITY ] ); + $this->assertContains( + Get_Site_Info::ABILITY, + $selector->get_tool_names( Tool_Selector::SCOPE_SITE ), + sprintf( 'An %s must be offered the site-info read.', $role ) + ); + } + } + + /** + * Under the MCP Adapter experiment's exposure filter, the ability is listed for MCP. + * + * @since x.x.x + */ + public function test_listed_for_mcp(): void { + wp_unregister_ability( Get_Site_Info::ABILITY ); + delete_option( Exposure_Overrides::OPTION_NAME ); + add_filter( 'wp_register_ability_args', array( Exposure_Overrides::class, 'filter_ability_args' ), 100, 2 ); + + $this->register_ability(); + + $meta = wp_get_ability( Get_Site_Info::ABILITY )->get_meta(); + + $this->assertTrue( $meta['mcp']['public'] ); + } +} diff --git a/tests/Integration/Includes/Experiments/AI_Workspace/Tool_PolicyTest.php b/tests/Integration/Includes/Experiments/AI_Workspace/Tool_PolicyTest.php index d52d73c6a..d52bb7289 100644 --- a/tests/Integration/Includes/Experiments/AI_Workspace/Tool_PolicyTest.php +++ b/tests/Integration/Includes/Experiments/AI_Workspace/Tool_PolicyTest.php @@ -1235,6 +1235,45 @@ static function () { ); } + /** + * `core/get-site-info` stays off the surface even once core gives it `open_world: false`. + * + * Core's site-info reader returns the admin email. The workspace offers + * `ai/get-site-info` instead, which never does, so this registers the core + * reader the way core would once that hint is added, with admission switched + * on, and checks the withheld list is what keeps it off. + * + * @since x.x.x + */ + public function test_core_get_site_info_is_withheld_with_perfect_annotations(): void { + $this->require_filtered_discovery(); + + if ( wp_has_ability( 'core/get-site-info' ) ) { + wp_unregister_ability( 'core/get-site-info' ); + } + + $ability = $this->register_fixture( + 'core/get-site-info', + array( + 'public' => true, + 'annotations' => $this->safe_annotations(), + ) + ); + + $policy = new Tool_Policy(); + + $this->assertTrue( + $policy->has_admissible_effect_class( $ability ), + 'Guard: the fixture passes the effect class, so only the withheld list can keep it off.' + ); + $this->assertNotContains( + 'core/get-site-info', + ( new Tool_Selector() )->get_tool_names( Tool_Selector::SCOPE_SITE ), + 'Core\'s site-info reader, which returns the admin email, must never reach the model.' + ); + $this->assertSame( Tool_Policy::REASON_WITHHELD, $policy->get_exclusion_reason( $ability ) ); + } + /** * `core/settings-get` stays off the surface even once core gives it `open_world: false`. * diff --git a/tests/Integration/Includes/Experiments/AI_Workspace/Tool_SelectorTest.php b/tests/Integration/Includes/Experiments/AI_Workspace/Tool_SelectorTest.php index a7490c075..cd3485bee 100644 --- a/tests/Integration/Includes/Experiments/AI_Workspace/Tool_SelectorTest.php +++ b/tests/Integration/Includes/Experiments/AI_Workspace/Tool_SelectorTest.php @@ -13,6 +13,7 @@ use WordPress\AI\Abilities\Content\Read_Content_Bodies; use WordPress\AI\Abilities\Content\Search_Content; use WordPress\AI\Abilities\Show_In_Abilities; +use WordPress\AI\Abilities\Site\Get_Site_Info; use WordPress\AI\Experiments\Abilities_Explorer\Ability_Handler; use WordPress\AI\Experiments\AI_Workspace\Ask_User; use WordPress\AI\Experiments\AI_Workspace\Propose_Drafts; @@ -74,6 +75,7 @@ class Tool_SelectorTest extends WP_UnitTestCase { 'ai/search-content', 'ai/read-content-bodies', 'ai/list-terms', + 'ai/get-site-info', 'ai/propose-drafts', 'ai/propose-template', 'ai/propose-post-changes', @@ -154,7 +156,7 @@ public function tearDown(): void { Test_Update_Kind::unregister_ability(); $ability_names = array_merge( - array( 'ai/search-content', 'ai/read-content-bodies', 'ai/list-terms', 'ai/propose-drafts', 'ai/propose-template', 'ai/propose-post-changes', 'ai/propose-site-identity', 'ai/ask-user', self::EDITOR_ABILITY ), + array( 'ai/search-content', 'ai/read-content-bodies', 'ai/list-terms', 'ai/get-site-info', 'ai/propose-drafts', 'ai/propose-template', 'ai/propose-post-changes', 'ai/propose-site-identity', 'ai/ask-user', self::EDITOR_ABILITY ), $this->registered ); @@ -1073,6 +1075,7 @@ private function use_curated_surface_only(): void { try { ( new Read_Content_Bodies() )->register(); ( new List_Terms() )->register(); + ( new Get_Site_Info() )->register(); ( new Propose_Drafts() )->register(); ( new Propose_Template() )->register(); ( new Propose_Post_Changes() )->register(); @@ -1198,8 +1201,8 @@ public function test_built_in_kinds_keep_their_capabilities(): void { $this->assertSame( 'edit_posts', $candidates['ai/propose-post-changes'] ); $this->assertSame( 'manage_options', $candidates['ai/propose-site-identity'] ); $this->assertSame( - array( 'ai/search-content', 'ai/read-content-bodies', 'ai/list-terms', 'ai/propose-drafts', 'ai/propose-template', 'ai/propose-post-changes', 'ai/propose-site-identity', 'ai/ask-user' ), - array_slice( array_keys( $candidates ), 0, 8 ) + array( 'ai/search-content', 'ai/read-content-bodies', 'ai/list-terms', 'ai/get-site-info', 'ai/propose-drafts', 'ai/propose-template', 'ai/propose-post-changes', 'ai/propose-site-identity', 'ai/ask-user' ), + array_slice( array_keys( $candidates ), 0, 9 ) ); } From e765cba93c94329ea17361cc784021b3ec56801f Mon Sep 17 00:00:00 2001 From: Jake Spurlock Date: Fri, 6 Nov 2026 18:16:28 -0800 Subject: [PATCH 2/8] feat(ai-workspace): find the admin screen for a request Part of #1287 (PR B, U7). The assistant can now answer "where do I hide my site from Google?" with a link to Settings -> Reading, through ai/find-admin-screens. - The ability matches the request against a curated map of 33 core admin screens on the server (titles plus keywords), with no nested model call, and returns up to five, best first. - It returns only screens the current user can open, as admin_url() links on the site's own host. A filtered entry whose path has a scheme, a leading slash or "..", is dropped. - Sites and plugins can add or remove entries with wpai_admin_screens. - The Site Editor is offered only on block themes and the Customizer only on classic ones. - A read ability like the others: any logged-in user, read-only, listed over MCP, on the workspace's curated tool list. #1250's palette ability (a nested model call over the palette's own commands) stays separate; it comes with the Command Palette slice. Co-Authored-By: Claude Opus 5.5 --- docs/experiments/ai-workspace.md | 33 ++ .../Abilities/Site/Find_Admin_Screens.php | 462 ++++++++++++++++++ includes/Abilities/Site/admin-screens.php | 244 +++++++++ .../Experiments/AI_Workspace/AI_Workspace.php | 8 + .../AI_Workspace/Tool_Selector.php | 13 +- readme.txt | 1 + .../Abilities/Site/Find_Admin_ScreensTest.php | 383 +++++++++++++++ .../AI_Workspace/Tool_SelectorTest.php | 69 +-- .../scenarios/workspace-navigate.json | 49 ++ .../experiments/ai-workspace-navigate.spec.ts | 86 ++++ 10 files changed, 1316 insertions(+), 32 deletions(-) create mode 100644 includes/Abilities/Site/Find_Admin_Screens.php create mode 100644 includes/Abilities/Site/admin-screens.php create mode 100644 tests/Integration/Includes/Abilities/Site/Find_Admin_ScreensTest.php create mode 100644 tests/e2e-testing/responses/Anthropic/scenarios/workspace-navigate.json create mode 100644 tests/e2e/specs/experiments/ai-workspace-navigate.spec.ts diff --git a/docs/experiments/ai-workspace.md b/docs/experiments/ai-workspace.md index e4bf3a370..4af71af01 100644 --- a/docs/experiments/ai-workspace.md +++ b/docs/experiments/ai-workspace.md @@ -55,6 +55,7 @@ The abilities offered to the model are not everything registered on the site. Th | `ai/read-content-bodies` | Returns the full body text of up to five posts named by ID | any authenticated user | | `ai/list-terms` | Lists the site's categories, tags and other public terms with how many published posts each holds | any authenticated user | | `ai/get-site-info` | Returns the site's name, tagline, home URL, language, timezone, date and time formats and active theme, with the WordPress and PHP versions for `manage_options` only | any authenticated user | +| `ai/find-admin-screens` | Finds up to five admin screens for a short description of a task, such as "hide my site from google", from a curated map; returns only screens the user can open, each with its title, menu section and `admin_url()` link | any authenticated user | | `ai/propose-drafts` | Records a proposed set of drafts for a person to approve; writes nothing | `edit_posts` | | `ai/propose-template` | Records one proposed block template for a person to approve; writes nothing | `edit_theme_options` | | `ai/ask-user` | Asks the person one question with two to five choices, which ends the turn until they answer; writes nothing | any authenticated user (the ability itself requires `manage_options`) | @@ -191,6 +192,17 @@ Registered alongside `ai/search-content`, shown in REST, and listed over MCP by It never returns the admin email, the WordPress address (`siteurl`), database details or the plugin list. That is why it sits on the floor while `core/get-environment-info` and `core/settings-get` stay on the [withheld list](#wpai_workspace_withheld_abilities): two version strings for administrators are a narrow exception to that list's rationale, not a way around it. It is annotated read-only, not destructive, idempotent and not open-world, so it stays admissible if declaration-based admission is switched on. +### `ai/find-admin-screens` + +Registered alongside `ai/search-content`, shown in REST, and listed over MCP like the other reads. It answers "where do I…" with a link. It takes one `query`, the task in the person's words (required, at most 200 characters), and returns `screens`: up to five `{ title, section, url }`, best match first, where `section` is the menu the screen sits under (such as `Settings`) and is absent for a top-level screen. "hide my site from google" returns Settings → Reading first; "stop spam comments" returns Settings → Discussion first. + +- **The map, not the menu.** The admin menu is not built during a REST request, so the screens come from a curated map of core screens in `includes/Abilities/Site/admin-screens.php`: the dashboard and updates, posts, categories, tags, pages, media, comments, themes, the Site Editor on a block theme or the Customizer on a classic one, plugins, users and your profile, Site Health, export, import, the personal-data export and erase tools, and the General, Writing, Reading, Discussion, Media, Permalinks and Privacy settings. Each entry carries the capability core requires to open it. [`wpai_admin_screens`](#wpai_admin_screens) adds or removes entries. +- **Matching on the server.** The query is lowercased, stripped of punctuation and common words such as "how", "my" and "change", and lightly stemmed, so "comments" matches "comment". A screen scores by how many query words its title, section or keywords contain; ties go to a title match, then to map order. There is no model call: the agent's own model chooses among the results. A query with no meaningful word, or one that matches nothing, returns an empty list rather than an error, so the model can try other words. +- **Only screens the user can open.** Every entry is checked with `current_user_can()` before it is scored, so an editor asking for "plugins" gets no Plugins screen and no Settings screen. That is why the ability needs only an authenticated user. +- **Only admin links.** Each `url` is `admin_url( path )`, and an entry whose `path` carries a scheme, a leading slash or backslash, or a parent directory is dropped, so a filter cannot point a result at another host. The transcript renders a link on the site's own host as a live anchor, and the ability's description tells the model to link the returned URL rather than build one. + +It is annotated read-only, not destructive, idempotent and not open-world. + ### `ai/read-content-bodies` The reading half of retrieval, and the largest increase in reachable content on this surface. Registered by this experiment for the same reason the search ability is: `core/content-query` belongs to the Custom Abilities experiment, and the workspace's reach must not change when a different experiment is switched off. @@ -507,6 +519,27 @@ add_filter( 'wpai_workspace_tool_admission_enabled', '__return_true' ); This is not the site owner's off switch. That one lives on the Abilities Explorer, is on by default, and is not going away. +### `wpai_admin_screens` + +Filters the screens `ai/find-admin-screens` can return. Each entry is an array with a `title`, a `path` relative to the admin directory (passed to `admin_url()`), the `capability` a user needs to be offered it, and optionally `keywords` (words or phrases a person might use for it) and a short `section`. An entry missing a title, a capability or a relative path is dropped. Earlier entries win ties. + +```php +add_filter( + 'wpai_admin_screens', + static function ( array $screens ): array { + $screens[] = array( + 'title' => 'Newsletter', + 'section' => 'Settings', + 'path' => 'options-general.php?page=my-newsletter', + 'keywords' => array( 'email', 'subscribers', 'mailing list' ), + 'capability' => 'manage_options', + ); + + return $screens; + } +); +``` + ### `wpai_workspace_write_proposals_enabled` Filters whether the assistant may propose changes to things that already exist: post fields, and the site title and tagline. Default true. Returning false removes `ai/propose-post-changes` and `ai/propose-site-identity` from the assistant's tools and from its instructions, and refuses approval of any such proposal already stored. Drafts and templates are not affected. diff --git a/includes/Abilities/Site/Find_Admin_Screens.php b/includes/Abilities/Site/Find_Admin_Screens.php new file mode 100644 index 000000000..df279c102 --- /dev/null +++ b/includes/Abilities/Site/Find_Admin_Screens.php @@ -0,0 +1,462 @@ + + */ + private const STOPWORDS = array( // phpcs:ignore SlevomatCodingStandard.Classes.DisallowMultiConstantDefinition -- This is a single array constant. + 'a', + 'about', + 'all', + 'am', + 'an', + 'and', + 'any', + 'are', + 'as', + 'at', + 'be', + 'by', + 'can', + 'change', + 'could', + 'do', + 'does', + 'edit', + 'find', + 'for', + 'from', + 'get', + 'go', + 'how', + 'i', + 'in', + 'into', + 'is', + 'it', + 'its', + 'manage', + 'me', + 'my', + 'need', + 'of', + 'on', + 'or', + 'our', + 'please', + 'screen', + 'set', + 'should', + 'show', + 'so', + 'some', + 'that', + 'the', + 'there', + 'this', + 'to', + 'turn', + 'up', + 'want', + 'way', + 'we', + 'what', + 'where', + 'which', + 'who', + 'why', + 'will', + 'with', + 'would', + 'you', + 'your', + ); + + /** + * Hooks the ability into the Abilities API. + * + * @since x.x.x + */ + public function init(): void { + add_action( 'wp_abilities_api_init', array( $this, 'register' ), 11 ); + } + + /** + * Registers the read-only `ai/find-admin-screens` ability. + * + * Must run on the `wp_abilities_api_init` hook. + * + * @since x.x.x + */ + public function register(): void { + if ( wp_has_ability( self::ABILITY ) ) { + wp_unregister_ability( self::ABILITY ); + } + + wp_register_ability( + self::ABILITY, + array( + 'label' => __( 'Find Admin Screens', 'ai' ), + 'description' => __( 'Finds the WordPress admin screens that handle a task, from a short description in the person\'s words, such as "hide my site from google" or "change the timezone". Returns up to five screens the current user can open, best match first, each with its title, its menu section and its admin URL. Link the person to a screen with the returned URL; never build an admin URL yourself. An empty list means no screen matched. Requires an authenticated user.', 'ai' ), + 'category' => WPAI_DEFAULT_ABILITY_CATEGORY, + 'input_schema' => array( + 'type' => 'object', + 'additionalProperties' => false, + 'required' => array( 'query' ), + 'properties' => array( + 'query' => array( + 'type' => 'string', + 'minLength' => 1, + 'maxLength' => self::MAX_QUERY_LENGTH, + 'description' => __( 'What the person wants to do or change, in a few words, such as "discourage search engines" or "approve comments".', 'ai' ), + ), + ), + ), + 'output_schema' => $this->get_output_schema(), + 'execute_callback' => array( $this, 'execute_find_admin_screens' ), + 'permission_callback' => array( $this, 'check_permission' ), + 'meta' => array( + 'annotations' => array( + 'readonly' => true, + 'destructive' => false, + 'idempotent' => true, + // This ability only reads a map held on the local site. + 'open_world' => false, + ), + 'show_in_rest' => true, + ), + ) + ); + } + + /** + * Permission callback for the `ai/find-admin-screens` ability. + * + * Any authenticated user may ask: each screen is checked against the user's + * own capabilities before it is returned, so the coarse gate has nothing to add. + * + * @since x.x.x + * + * @param mixed $input Optional. The ability input. Default empty array. + * @return bool True if the request may proceed. + */ + public function check_permission( $input = array() ): bool { + unset( $input ); + + return is_user_logged_in(); + } + + /** + * Executes the `ai/find-admin-screens` ability. + * + * @since x.x.x + * + * @param mixed $input Optional. The ability input. Default empty array. + * @return array{screens: list} The matching screens, best first. + */ + public function execute_find_admin_screens( $input = array() ): array { + $query = is_array( $input ) && isset( $input['query'] ) && is_string( $input['query'] ) ? $input['query'] : ''; + $query = trim( mb_substr( trim( $query ), 0, self::MAX_QUERY_LENGTH ) ); + $terms = array_values( array_unique( $this->tokenize( $query ) ) ); + + if ( array() === $terms ) { + return array( 'screens' => array() ); + } + + $scored = array(); + + foreach ( $this->get_screens() as $index => $screen ) { + // phpcs:ignore WordPress.WP.Capabilities.Undetermined -- Each screen names the capability core requires to open it. + if ( ! current_user_can( $screen['capability'] ) ) { + continue; + } + + $title_words = $this->tokenize( $screen['title'] ); + $words = array_merge( + $title_words, + $this->tokenize( $screen['section'] ), + $this->tokenize( implode( ' ', $screen['keywords'] ) ) + ); + + $hits = count( array_intersect( $terms, $words ) ); + $title_hits = count( array_intersect( $terms, $title_words ) ); + + if ( 0 === $hits ) { + continue; + } + + $scored[] = array( + 'hits' => $hits, + 'title_hits' => $title_hits, + 'index' => $index, + 'screen' => $screen, + ); + } + + // Most query words matched first, then a match on the title, then map order. + usort( + $scored, + static function ( array $a, array $b ): int { + return array( $b['hits'], $b['title_hits'], $a['index'] ) <=> array( $a['hits'], $a['title_hits'], $b['index'] ); + } + ); + + $screens = array(); + + foreach ( array_slice( $scored, 0, self::MAX_RESULTS ) as $match ) { + $screen = $match['screen']; + $item = array( + 'title' => $screen['title'], + 'url' => admin_url( $screen['path'] ), + ); + + if ( '' !== $screen['section'] ) { + $item['section'] = $screen['section']; + } + + $screens[] = $item; + } + + return array( 'screens' => $screens ); + } + + /** + * Returns the screen map, filtered and validated. + * + * An entry is dropped unless it has a title, a capability, and a path that is + * relative to the admin directory: no scheme, no leading slash or backslash, so + * `admin_url()` cannot be pointed at another host. + * + * @since x.x.x + * + * @return list, capability: string}> The screens. + */ + private function get_screens(): array { + $screens = require __DIR__ . '/admin-screens.php'; + + /** + * Filters the admin screens the `ai/find-admin-screens` ability can return. + * + * Each entry is an array with a `title`, a `path` relative to the admin + * directory (passed to `admin_url()`), a `capability` the user must have + * to be offered it, and optionally `keywords` (a list of words or phrases + * a person might use for it) and a short `section` such as "Settings". + * Entries earlier in the list win ties. + * + * @since x.x.x + * + * @param array> $screens The curated core screens. + */ + $screens = apply_filters( 'wpai_admin_screens', is_array( $screens ) ? $screens : array() ); + + if ( ! is_array( $screens ) ) { + return array(); + } + + $valid = array(); + + foreach ( $screens as $screen ) { + if ( ! is_array( $screen ) ) { + continue; + } + + $title = isset( $screen['title'] ) && is_string( $screen['title'] ) ? trim( $screen['title'] ) : ''; + $path = isset( $screen['path'] ) && is_string( $screen['path'] ) ? trim( $screen['path'] ) : ''; + $capability = isset( $screen['capability'] ) && is_string( $screen['capability'] ) ? trim( $screen['capability'] ) : ''; + $section = isset( $screen['section'] ) && is_string( $screen['section'] ) ? trim( $screen['section'] ) : ''; + $keywords = isset( $screen['keywords'] ) && is_array( $screen['keywords'] ) ? array_values( array_filter( $screen['keywords'], 'is_string' ) ) : array(); + + if ( '' === $title || '' === $capability || ! $this->is_admin_path( $path ) ) { + continue; + } + + $valid[] = array( + 'title' => $title, + 'section' => $section, + 'path' => $path, + 'keywords' => $keywords, + 'capability' => $capability, + ); + } + + return $valid; + } + + /** + * Whether a path is relative to the admin directory. + * + * @since x.x.x + * + * @param string $path The path. + * @return bool True for a path such as `options-reading.php` or `admin.php?page=x`. + */ + private function is_admin_path( string $path ): bool { + if ( '' === $path || 1 === preg_match( '#^[/\\\\]|^[a-z][a-z0-9+.\-]*:#i', $path ) ) { + return false; + } + + // Nothing before the query string may carry a scheme, a host or a parent directory. + $file = (string) strtok( $path, '?#' ); + + return 1 === preg_match( '#^[a-z0-9_\-./]+$#i', $file ) && false === strpos( $file, '..' ) && false === strpos( $file, '//' ); + } + + /** + * Splits text into lowercase, lightly stemmed words without stopwords. + * + * @since x.x.x + * + * @param string $text The text. + * @return list The words. + */ + private function tokenize( string $text ): array { + $text = function_exists( 'mb_strtolower' ) ? mb_strtolower( $text ) : strtolower( $text ); + $parts = preg_split( '/[^\p{L}\p{N}]+/u', $text, -1, PREG_SPLIT_NO_EMPTY ); + + if ( ! is_array( $parts ) ) { + return array(); + } + + $words = array(); + + foreach ( $parts as $part ) { + if ( in_array( $part, self::STOPWORDS, true ) ) { + continue; + } + + $words[] = $this->stem( $part ); + } + + return $words; + } + + /** + * Reduces a word to a rough stem, so "comments" matches "comment". + * + * @since x.x.x + * + * @param string $word A lowercase word. + * @return string The stem. + */ + private function stem( string $word ): string { + $length = strlen( $word ); + + if ( $length > 4 && 'ies' === substr( $word, -3 ) ) { + return substr( $word, 0, -3 ) . 'y'; + } + + if ( $length > 5 && 'ing' === substr( $word, -3 ) ) { + return substr( $word, 0, -3 ); + } + + if ( $length > 3 && 's' === substr( $word, -1 ) && 'ss' !== substr( $word, -2 ) ) { + return substr( $word, 0, -1 ); + } + + return $word; + } + + /** + * Builds the output schema for the `ai/find-admin-screens` ability. + * + * @since x.x.x + * + * @return array The output JSON Schema. + */ + private function get_output_schema(): array { + return array( + 'type' => 'object', + 'additionalProperties' => false, + 'required' => array( 'screens' ), + 'properties' => array( + 'screens' => array( + 'type' => 'array', + 'maxItems' => self::MAX_RESULTS, + 'description' => __( 'The matching screens, best match first. Empty when nothing matched.', 'ai' ), + 'items' => array( + 'type' => 'object', + 'additionalProperties' => false, + 'required' => array( 'title', 'url' ), + 'properties' => array( + 'title' => array( + 'type' => 'string', + 'description' => __( 'The screen\'s menu title, such as Reading.', 'ai' ), + ), + 'section' => array( + 'type' => 'string', + 'description' => __( 'The admin menu the screen sits under, such as Settings. Absent for a top-level screen.', 'ai' ), + ), + 'url' => array( + 'type' => 'string', + 'format' => 'uri', + 'description' => __( 'The screen\'s admin URL.', 'ai' ), + ), + ), + ), + ), + ), + ); + } +} diff --git a/includes/Abilities/Site/admin-screens.php b/includes/Abilities/Site/admin-screens.php new file mode 100644 index 000000000..d3259938c --- /dev/null +++ b/includes/Abilities/Site/admin-screens.php @@ -0,0 +1,244 @@ + __( 'Dashboard', 'ai' ), + 'path' => 'index.php', + 'keywords' => array( 'home', 'overview', 'at a glance', 'activity', 'welcome' ), + 'capability' => 'read', + ), + array( + 'title' => __( 'Updates', 'ai' ), + 'section' => __( 'Dashboard', 'ai' ), + 'path' => 'update-core.php', + 'keywords' => array( 'update', 'upgrade', 'new version', 'wordpress version', 'auto updates' ), + 'capability' => 'update_core', + ), + array( + 'title' => __( 'Posts', 'ai' ), + 'path' => 'edit.php', + 'keywords' => array( 'all posts', 'blog posts', 'articles', 'drafts', 'published', 'scheduled', 'edit post', 'delete post', 'trash' ), + 'capability' => 'edit_posts', + ), + array( + 'title' => __( 'Add New Post', 'ai' ), + 'section' => __( 'Posts', 'ai' ), + 'path' => 'post-new.php', + 'keywords' => array( 'new post', 'write', 'create post', 'blog post', 'article', 'publish' ), + 'capability' => 'edit_posts', + ), + array( + 'title' => __( 'Categories', 'ai' ), + 'section' => __( 'Posts', 'ai' ), + 'path' => 'edit-tags.php?taxonomy=category', + 'keywords' => array( 'category', 'taxonomy', 'organize posts' ), + 'capability' => 'manage_categories', + ), + array( + 'title' => __( 'Tags', 'ai' ), + 'section' => __( 'Posts', 'ai' ), + 'path' => 'edit-tags.php?taxonomy=post_tag', + 'keywords' => array( 'tag', 'taxonomy', 'post tags' ), + 'capability' => 'manage_categories', + ), + array( + 'title' => __( 'Media Library', 'ai' ), + 'section' => __( 'Media', 'ai' ), + 'path' => 'upload.php', + 'keywords' => array( 'media', 'images', 'photos', 'files', 'uploads', 'video', 'audio', 'pdf', 'attachments' ), + 'capability' => 'upload_files', + ), + array( + 'title' => __( 'Pages', 'ai' ), + 'path' => 'edit.php?post_type=page', + 'keywords' => array( 'all pages', 'static pages', 'about page', 'contact page', 'edit page' ), + 'capability' => 'edit_pages', + ), + array( + 'title' => __( 'Add New Page', 'ai' ), + 'section' => __( 'Pages', 'ai' ), + 'path' => 'post-new.php?post_type=page', + 'keywords' => array( 'new page', 'create page' ), + 'capability' => 'edit_pages', + ), + array( + 'title' => __( 'Comments', 'ai' ), + 'path' => 'edit-comments.php', + 'keywords' => array( 'approve', 'reply', 'pending', 'moderate', 'delete comment' ), + 'capability' => 'edit_posts', + ), + array( + 'title' => __( 'Themes', 'ai' ), + 'section' => $wpai_appearance, + 'path' => 'themes.php', + 'keywords' => array( 'theme', 'appearance', 'look', 'design', 'switch theme', 'install theme', 'activate theme' ), + 'capability' => 'switch_themes', + ), +); + +if ( wp_is_block_theme() ) { + $wpai_screens[] = array( + 'title' => __( 'Editor', 'ai' ), + 'section' => $wpai_appearance, + 'path' => 'site-editor.php', + 'keywords' => array( 'site editor', 'full site editing', 'templates', 'template parts', 'header', 'footer', 'navigation', 'menus', 'styles', 'colors', 'fonts', 'typography', 'layout', 'patterns', 'design' ), + 'capability' => 'edit_theme_options', + ); +} else { + $wpai_screens[] = array( + 'title' => __( 'Customize', 'ai' ), + 'section' => $wpai_appearance, + 'path' => 'customize.php', + 'keywords' => array( 'customizer', 'header', 'footer', 'colors', 'background', 'logo', 'site icon', 'favicon', 'menus', 'widgets', 'additional css', 'design' ), + 'capability' => 'customize', + ); +} + +$wpai_screens = array_merge( + $wpai_screens, + array( + array( + 'title' => __( 'Plugins', 'ai' ), + 'path' => 'plugins.php', + 'keywords' => array( 'plugin', 'extensions', 'addons', 'activate', 'deactivate', 'installed plugins' ), + 'capability' => 'activate_plugins', + ), + array( + 'title' => __( 'Add New Plugin', 'ai' ), + 'section' => __( 'Plugins', 'ai' ), + 'path' => 'plugin-install.php', + 'keywords' => array( 'install plugin', 'new plugin', 'plugin directory', 'upload plugin' ), + 'capability' => 'install_plugins', + ), + array( + 'title' => __( 'Users', 'ai' ), + 'path' => 'users.php', + 'keywords' => array( 'all users', 'accounts', 'members', 'authors', 'editors', 'roles', 'delete user', 'people' ), + 'capability' => 'list_users', + ), + array( + 'title' => __( 'Add New User', 'ai' ), + 'section' => __( 'Users', 'ai' ), + 'path' => 'user-new.php', + 'keywords' => array( 'new user', 'invite', 'create account', 'add author' ), + 'capability' => 'create_users', + ), + array( + 'title' => __( 'Profile', 'ai' ), + 'section' => __( 'Users', 'ai' ), + 'path' => 'profile.php', + 'keywords' => array( 'my profile', 'my account', 'password', 'email address', 'display name', 'nickname', 'bio', 'application passwords', 'admin color scheme', 'toolbar' ), + 'capability' => 'read', + ), + array( + 'title' => __( 'Site Health', 'ai' ), + 'section' => $wpai_tools, + 'path' => 'site-health.php', + 'keywords' => array( 'health check', 'status', 'diagnostics', 'debug', 'performance', 'security', 'php version', 'server info', 'problems' ), + 'capability' => 'view_site_health_checks', + ), + array( + 'title' => __( 'Export', 'ai' ), + 'section' => $wpai_tools, + 'path' => 'export.php', + 'keywords' => array( 'backup content', 'download content', 'wxr', 'xml', 'migrate' ), + 'capability' => 'export', + ), + array( + 'title' => __( 'Import', 'ai' ), + 'section' => $wpai_tools, + 'path' => 'import.php', + 'keywords' => array( 'importer', 'upload content', 'wxr', 'migrate', 'move from blogger', 'rss import' ), + 'capability' => 'import', + ), + array( + 'title' => __( 'Export Personal Data', 'ai' ), + 'section' => $wpai_tools, + 'path' => 'export-personal-data.php', + 'keywords' => array( 'gdpr', 'privacy request', 'data request', 'personal data', 'user data' ), + 'capability' => 'export_others_personal_data', + ), + array( + 'title' => __( 'Erase Personal Data', 'ai' ), + 'section' => $wpai_tools, + 'path' => 'erase-personal-data.php', + 'keywords' => array( 'gdpr', 'privacy request', 'delete personal data', 'right to be forgotten', 'erasure', 'user data' ), + 'capability' => 'erase_others_personal_data', + ), + array( + 'title' => __( 'General', 'ai' ), + 'section' => $wpai_settings, + 'path' => 'options-general.php', + 'keywords' => array( 'site title', 'tagline', 'site name', 'timezone', 'time zone', 'language', 'locale', 'date format', 'time format', 'week starts on', 'admin email', 'site address', 'url', 'membership', 'registration', 'new user default role' ), + 'capability' => 'manage_options', + ), + array( + 'title' => __( 'Writing', 'ai' ), + 'section' => $wpai_settings, + 'path' => 'options-writing.php', + 'keywords' => array( 'default post category', 'default post format', 'post via email', 'update services', 'ping', 'editor' ), + 'capability' => 'manage_options', + ), + array( + 'title' => __( 'Reading', 'ai' ), + 'section' => $wpai_settings, + 'path' => 'options-reading.php', + 'keywords' => array( 'search engine visibility', 'discourage search engines', 'google', 'bing', 'indexing', 'noindex', 'hide', 'seo', 'homepage', 'home page', 'front page', 'posts page', 'blog page', 'posts per page', 'blog pages show at most', 'feed', 'rss', 'syndication' ), + 'capability' => 'manage_options', + ), + array( + 'title' => __( 'Discussion', 'ai' ), + 'section' => $wpai_settings, + 'path' => 'options-discussion.php', + 'keywords' => array( 'comments', 'spam', 'stop', 'block', 'prevent', 'moderation', 'comment approval', 'blocklist', 'disallowed keys', 'pingbacks', 'trackbacks', 'avatars', 'gravatar', 'close comments', 'disable comments', 'notifications' ), + 'capability' => 'manage_options', + ), + array( + 'title' => __( 'Media', 'ai' ), + 'section' => $wpai_settings, + 'path' => 'options-media.php', + 'keywords' => array( 'image sizes', 'thumbnail size', 'medium size', 'large size', 'crop', 'uploads folder', 'organize uploads' ), + 'capability' => 'manage_options', + ), + array( + 'title' => __( 'Permalinks', 'ai' ), + 'section' => $wpai_settings, + 'path' => 'options-permalink.php', + 'keywords' => array( 'url structure', 'pretty urls', 'slugs', 'links', 'category base', 'tag base', '404' ), + 'capability' => 'manage_options', + ), + array( + 'title' => __( 'Privacy', 'ai' ), + 'section' => $wpai_settings, + 'path' => 'options-privacy.php', + 'keywords' => array( 'privacy policy', 'policy page', 'gdpr', 'cookies' ), + 'capability' => 'manage_privacy_options', + ), + ) +); + +return $wpai_screens; diff --git a/includes/Experiments/AI_Workspace/AI_Workspace.php b/includes/Experiments/AI_Workspace/AI_Workspace.php index bbbfc0a3d..57e21d662 100644 --- a/includes/Experiments/AI_Workspace/AI_Workspace.php +++ b/includes/Experiments/AI_Workspace/AI_Workspace.php @@ -13,6 +13,7 @@ use WordPress\AI\Abilities\Content\Read_Content_Bodies; use WordPress\AI\Abilities\Content\Search_Content; use WordPress\AI\Abilities\Show_In_Abilities; +use WordPress\AI\Abilities\Site\Find_Admin_Screens; use WordPress\AI\Abilities\Site\Get_Site_Info; use WordPress\AI\Abstracts\Abstract_Feature; use WordPress\AI\Asset_Loader; @@ -127,6 +128,13 @@ public function register(): void { */ ( new Get_Site_Info() )->init(); + /* + * "Where do I…" answered with a link: a curated map of admin screens, + * matched on the server and filtered to the screens the user can open. + * Registered here for the same reason as search. + */ + ( new Find_Admin_Screens() )->init(); + /* * The model's reach toward the write path. It stores a proposal and * writes nothing; it is withheld from the REST and MCP surfaces because diff --git a/includes/Experiments/AI_Workspace/Tool_Selector.php b/includes/Experiments/AI_Workspace/Tool_Selector.php index bc90d42c7..3f0fa4a99 100644 --- a/includes/Experiments/AI_Workspace/Tool_Selector.php +++ b/includes/Experiments/AI_Workspace/Tool_Selector.php @@ -191,7 +191,7 @@ public function __construct( ?Tool_Policy $policy = null, ?Proposal_Store $propo * @var array */ private const DEFAULT_CANDIDATES = array( // phpcs:ignore SlevomatCodingStandard.Classes.DisallowMultiConstantDefinition -- This is a single array constant. - self::SEARCH_ABILITY => '', + self::SEARCH_ABILITY => '', /* * Reading is filtered row by row at execute time against the requesting * user's own capabilities, so the coarse gate has nothing left to add: a @@ -199,14 +199,19 @@ public function __construct( ?Tool_Policy $policy = null, ?Proposal_Store $propo * user who could legitimately read something with it, while the rows they * may not read are withheld either way. */ - self::READ_ABILITY => '', + self::READ_ABILITY => '', // Term names and post counts are already public, like search results. - 'ai/list-terms' => '', + 'ai/list-terms' => '', /* * The output is already filtered per user: the versions are added only * for `manage_options`, and the rest is visible on the front end. */ - 'ai/get-site-info' => '', + 'ai/get-site-info' => '', + /* + * Each screen is checked against the user's own capabilities before it is + * returned, so a user is only ever linked to a screen they can open. + */ + 'ai/find-admin-screens' => '', ); /** diff --git a/readme.txt b/readme.txt index 91786b860..740c7faa5 100644 --- a/readme.txt +++ b/readme.txt @@ -234,6 +234,7 @@ Go to `Plugins` and deactivate AI. If you can't reach the admin, deactivate it w - New Experiment: AI Workspace; a dedicated `Tools -> AI Workspace` screen where you hold a multi-step, site-aware conversation with an assistant. The assistant can search your content under your own capabilities, renders post results as a table, and writes nothing until you approve a proposal, which shows the exact values -- including the post status -- that will be written ([#282](https://github.com/WordPress/ai/issues/282)). - New `ai/search-content` Ability that runs a bounded, capability-filtered full-text search across the post types exposed to abilities, returning titles and excerpts rather than post bodies ([#282](https://github.com/WordPress/ai/issues/282)). - New `ai/get-site-info` Ability that returns the site's name, tagline, home URL, language, timezone, date and time formats, active theme and whether it is a block theme, plus the WordPress and PHP versions for users who can `manage_options`. It never returns the admin email, the WordPress address, database details or the plugin list, which is why the AI Workspace offers it while withholding the broad `core/get-environment-info` and `core/settings-get` ([#1287](https://github.com/WordPress/ai/issues/1287)). +- New `ai/find-admin-screens` Ability that answers "where do I…" with links: given a short description such as "hide my site from google", it returns up to five matching admin screens from a curated map of core screens, only those the current user can open, each linked with `admin_url()`. Matching runs on the server with no model call, and the map is filterable through `wpai_admin_screens` ([#1287](https://github.com/WordPress/ai/issues/1287)). - The AI Workspace's tool surface is no longer a fixed list. An ability exposed to the surface - through `meta.public`, or by naming the `ai-workspace` channel - and annotated `readonly: true`, `destructive: false`, `open_world: false` - can be offered to the assistant alongside the three that ship with it. Admission defaults to refusing: an ability that is not public, and has not opted in, is never offered. Declaration-based admission is itself switched **off** until [#354](https://github.com/WordPress/ai/issues/354) settles the channel name, so the shipped surface is still the three curated abilities; `add_filter( 'wpai_workspace_tool_admission_enabled', '__return_true' )`, or the `WPAI_WORKSPACE_TOOL_ADMISSION` constant, turns it on to try it. A short list of core abilities that read personal data, settings or environment detail is never admitted whatever they declare, filterable through `wpai_workspace_withheld_abilities`. Exposure and the annotations are both the ability author's self-attestation, and the effect class is a declared intent rather than an enforced property: the site owner's Explorer controls and the execute-time `permission_callback` remain the boundaries ([#1003](https://github.com/WordPress/ai/issues/1003)). - The Abilities Explorer shows which abilities the AI Workspace assistant can call, the exact description text the model receives, and why any other ability is excluded. A site owner can remove an ability from the surface or switch the policy off entirely and return to the three that ship ([#1003](https://github.com/WordPress/ai/issues/1003)). diff --git a/tests/Integration/Includes/Abilities/Site/Find_Admin_ScreensTest.php b/tests/Integration/Includes/Abilities/Site/Find_Admin_ScreensTest.php new file mode 100644 index 000000000..37c71c13d --- /dev/null +++ b/tests/Integration/Includes/Abilities/Site/Find_Admin_ScreensTest.php @@ -0,0 +1,383 @@ + + */ + private static $user_ids = array(); + + /** + * Creates the shared users. + * + * @since x.x.x + * + * @param \WP_UnitTest_Factory $factory The unit test factory. + */ + public static function wpSetUpBeforeClass( $factory ): void { + self::$user_ids = array( + 'administrator' => $factory->user->create( array( 'role' => 'administrator' ) ), + 'editor' => $factory->user->create( array( 'role' => 'editor' ) ), + 'subscriber' => $factory->user->create( array( 'role' => 'subscriber' ) ), + ); + } + + /** + * Set up test case. + * + * @since x.x.x + */ + public function setUp(): void { + parent::setUp(); + + $this->register_ability(); + } + + /** + * Tear down test case. + * + * @since x.x.x + */ + public function tearDown(): void { + remove_all_filters( 'wpai_admin_screens' ); + remove_filter( 'wp_register_ability_args', array( Exposure_Overrides::class, 'filter_ability_args' ), 100 ); + + if ( wp_has_ability( Find_Admin_Screens::ABILITY ) ) { + wp_unregister_ability( Find_Admin_Screens::ABILITY ); + } + + wp_set_current_user( 0 ); + + parent::tearDown(); + } + + /** + * Registers the ability inside a faked `wp_abilities_api_init` action. + * + * @since x.x.x + */ + private function register_ability(): void { + global $wp_current_filter; + $wp_current_filter[] = 'wp_abilities_api_init'; // phpcs:ignore WordPress.WP.GlobalVariablesOverride.Prohibited -- Faking the action context to register within it. + try { + ( new Find_Admin_Screens() )->register(); + } finally { + array_pop( $wp_current_filter ); + } + } + + /** + * Runs the ability as a user with the given role. + * + * @since x.x.x + * + * @param string $role The role to run as. + * @param string $query The query. + * @return mixed The ability result. + */ + private function find_as( string $role, string $query ) { + wp_set_current_user( self::$user_ids[ $role ] ); + + return wp_get_ability( Find_Admin_Screens::ABILITY )->execute( array( 'query' => $query ) ); + } + + /** + * Returns the URLs of a successful result. + * + * @since x.x.x + * + * @param mixed $result The ability result. + * @return list The URLs, best match first. + */ + private function urls( $result ): array { + $this->assertIsArray( $result ); + $this->assertArrayHasKey( 'screens', $result ); + + return array_values( wp_list_pluck( $result['screens'], 'url' ) ); + } + + /** + * "hide my site from google" sends an administrator to Settings, Reading first. + * + * @since x.x.x + */ + public function test_hiding_the_site_from_google_finds_reading_settings_first(): void { + $result = $this->find_as( 'administrator', 'How do I hide my site from Google?' ); + $urls = $this->urls( $result ); + + $this->assertNotEmpty( $urls ); + $this->assertSame( admin_url( 'options-reading.php' ), $urls[0] ); + $this->assertSame( 'Reading', $result['screens'][0]['title'] ); + $this->assertSame( 'Settings', $result['screens'][0]['section'] ); + } + + /** + * "stop spam comments" sends an administrator to Settings, Discussion first. + * + * @since x.x.x + */ + public function test_stopping_spam_comments_finds_discussion_settings_first(): void { + $urls = $this->urls( $this->find_as( 'administrator', 'stop spam comments' ) ); + + $this->assertSame( admin_url( 'options-discussion.php' ), $urls[0] ); + } + + /** + * Asking where the timezone is set finds Settings, General first. + * + * @since x.x.x + */ + public function test_changing_the_timezone_finds_general_settings_first(): void { + $urls = $this->urls( $this->find_as( 'administrator', 'Where do I change the timezone?' ) ); + + $this->assertSame( admin_url( 'options-general.php' ), $urls[0] ); + } + + /** + * No more than five screens come back. + * + * @since x.x.x + */ + public function test_returns_at_most_five_screens(): void { + $urls = $this->urls( $this->find_as( 'administrator', 'settings posts pages comments users plugins themes media' ) ); + + $this->assertCount( 5, $urls ); + } + + /** + * An editor asking for plugins gets no Plugins screen, and no Settings screen either. + * + * @since x.x.x + */ + public function test_editor_asking_for_plugins_gets_no_plugins_or_settings_screen(): void { + foreach ( array( 'plugins', 'install a plugin', 'change site settings', 'discourage search engines' ) as $query ) { + foreach ( $this->urls( $this->find_as( 'editor', $query ) ) as $url ) { + $this->assertStringNotContainsString( 'plugin', $url, $query ); + $this->assertStringNotContainsString( 'options-', $url, $query ); + } + } + + // The same query does reach the Plugins screen for an administrator. + $this->assertContains( admin_url( 'plugins.php' ), $this->urls( $this->find_as( 'administrator', 'plugins' ) ) ); + } + + /** + * A screen added through `wpai_admin_screens` with its own capability is offered only to a user who has it. + * + * @since x.x.x + */ + public function test_filter_added_screen_appears_only_for_users_with_its_capability(): void { + add_filter( + 'wpai_admin_screens', + static function ( array $screens ): array { + $screens[] = array( + 'title' => 'Gizmo Dashboard', + 'path' => 'admin.php?page=gizmo', + 'keywords' => array( 'gizmo', 'widgets' ), + 'capability' => self::CUSTOM_CAP, + ); + + return $screens; + } + ); + + $gizmo = admin_url( 'admin.php?page=gizmo' ); + + $this->assertNotContains( $gizmo, $this->urls( $this->find_as( 'administrator', 'gizmo' ) ) ); + + $editor = get_user_by( 'id', self::$user_ids['editor'] ); + $editor->add_cap( self::CUSTOM_CAP ); + + try { + $this->assertSame( $gizmo, $this->urls( $this->find_as( 'editor', 'gizmo' ) )[0] ); + $this->assertNotContains( $gizmo, $this->urls( $this->find_as( 'administrator', 'gizmo' ) ) ); + } finally { + $editor->remove_cap( self::CUSTOM_CAP ); + } + } + + /** + * The filter can remove a core screen. + * + * @since x.x.x + */ + public function test_filter_can_remove_a_core_screen(): void { + add_filter( + 'wpai_admin_screens', + static function ( array $screens ): array { + return array_values( + array_filter( + $screens, + static function ( $screen ): bool { + return 'options-reading.php' !== $screen['path']; + } + ) + ); + } + ); + + $this->assertNotContains( admin_url( 'options-reading.php' ), $this->urls( $this->find_as( 'administrator', 'hide my site from google' ) ) ); + } + + /** + * Every URL is on the admin host, including for a filter-added entry that names another site. + * + * @since x.x.x + */ + public function test_every_url_is_on_the_admin_host(): void { + add_filter( + 'wpai_admin_screens', + static function ( array $screens ): array { + foreach ( array( 'https://evil.example/steal', '//evil.example/steal', '/\\evil.example/steal', 'javascript:alert(1)' ) as $path ) { + $screens[] = array( + 'title' => 'Evil escape', + 'path' => $path, + 'keywords' => array( 'escape' ), + 'capability' => 'read', + ); + } + + return $screens; + } + ); + + $admin_host = wp_parse_url( admin_url(), PHP_URL_HOST ); + $admin_base = admin_url(); + + foreach ( array( 'escape', 'hide my site from google', 'stop spam comments', 'users profile password', 'export import tools', 'theme editor customize' ) as $query ) { + foreach ( $this->urls( $this->find_as( 'administrator', $query ) ) as $url ) { + $this->assertSame( $admin_host, wp_parse_url( $url, PHP_URL_HOST ), $url ); + $this->assertStringStartsWith( $admin_base, $url ); + $this->assertStringNotContainsString( 'evil', $url ); + } + } + } + + /** + * A query made only of stopwords or punctuation finds nothing, as an empty list rather than an error. + * + * @since x.x.x + */ + public function test_stopword_only_query_returns_an_empty_list(): void { + foreach ( array( 'how do I', ' ', '?!', 'where is the' ) as $query ) { + $result = $this->find_as( 'administrator', $query ); + + $this->assertIsArray( $result, $query ); + $this->assertSame( array(), $result['screens'], $query ); + } + } + + /** + * A visitor who is not logged in is refused. + * + * @since x.x.x + */ + public function test_logged_out_visitor_is_refused(): void { + wp_set_current_user( 0 ); + + $this->assertWPError( wp_get_ability( Find_Admin_Screens::ABILITY )->execute( array( 'query' => 'plugins' ) ) ); + } + + /** + * Registration carries a category and the read-only, closed-world annotations. + * + * @since x.x.x + */ + public function test_registration_has_a_category_and_read_only_annotations(): void { + $ability = wp_get_ability( Find_Admin_Screens::ABILITY ); + + $this->assertNotNull( $ability ); + $this->assertSame( WPAI_DEFAULT_ABILITY_CATEGORY, $ability->get_category() ); + + $meta = $ability->get_meta(); + + $this->assertTrue( $meta['annotations']['readonly'] ); + $this->assertFalse( $meta['annotations']['destructive'] ); + $this->assertTrue( $meta['annotations']['idempotent'] ); + $this->assertFalse( $meta['annotations']['open_world'] ); + $this->assertTrue( $meta['show_in_rest'] ); + + $input = $ability->get_input_schema(); + + $this->assertSame( array( 'query' ), $input['required'] ); + $this->assertSame( 200, $input['properties']['query']['maxLength'] ); + } + + /** + * With policy admission off, as it ships, the ability is declared to the model for an administrator and an editor. + * + * @since x.x.x + */ + public function test_declared_to_the_model_for_administrator_and_editor_with_admission_off(): void { + $this->assertFalse( ( new Tool_Policy() )->admission_is_enabled(), 'Admission must be off, as it ships.' ); + + foreach ( array( 'administrator', 'editor' ) as $role ) { + wp_set_current_user( self::$user_ids[ $role ] ); + + $selector = new Tool_Selector(); + + $this->assertArrayHasKey( Find_Admin_Screens::ABILITY, $selector->get_candidates() ); + $this->assertSame( '', $selector->get_candidates()[ Find_Admin_Screens::ABILITY ] ); + $this->assertContains( + Find_Admin_Screens::ABILITY, + $selector->get_tool_names( Tool_Selector::SCOPE_SITE ), + sprintf( 'An %s must be offered the screen finder.', $role ) + ); + } + } + + /** + * Under the MCP Adapter experiment's exposure filter, the ability is listed for MCP. + * + * @since x.x.x + */ + public function test_listed_for_mcp(): void { + wp_unregister_ability( Find_Admin_Screens::ABILITY ); + delete_option( Exposure_Overrides::OPTION_NAME ); + add_filter( 'wp_register_ability_args', array( Exposure_Overrides::class, 'filter_ability_args' ), 100, 2 ); + + $this->register_ability(); + + $meta = wp_get_ability( Find_Admin_Screens::ABILITY )->get_meta(); + + $this->assertTrue( $meta['mcp']['public'] ); + } +} diff --git a/tests/Integration/Includes/Experiments/AI_Workspace/Tool_SelectorTest.php b/tests/Integration/Includes/Experiments/AI_Workspace/Tool_SelectorTest.php index cd3485bee..1ec4fc6cc 100644 --- a/tests/Integration/Includes/Experiments/AI_Workspace/Tool_SelectorTest.php +++ b/tests/Integration/Includes/Experiments/AI_Workspace/Tool_SelectorTest.php @@ -13,8 +13,8 @@ use WordPress\AI\Abilities\Content\Read_Content_Bodies; use WordPress\AI\Abilities\Content\Search_Content; use WordPress\AI\Abilities\Show_In_Abilities; +use WordPress\AI\Abilities\Site\Find_Admin_Screens; use WordPress\AI\Abilities\Site\Get_Site_Info; -use WordPress\AI\Experiments\Abilities_Explorer\Ability_Handler; use WordPress\AI\Experiments\AI_Workspace\Ask_User; use WordPress\AI\Experiments\AI_Workspace\Propose_Drafts; use WordPress\AI\Experiments\AI_Workspace\Propose_Post_Changes; @@ -22,6 +22,7 @@ use WordPress\AI\Experiments\AI_Workspace\Propose_Template; use WordPress\AI\Experiments\AI_Workspace\Tool_Policy; use WordPress\AI\Experiments\AI_Workspace\Tool_Selector; +use WordPress\AI\Experiments\Abilities_Explorer\Ability_Handler; use WordPress\AI\Tests\Integration\Includes\Experiments\AI_Workspace\Fixtures\Test_Update_Kind; /** @@ -76,6 +77,7 @@ class Tool_SelectorTest extends WP_UnitTestCase { 'ai/read-content-bodies', 'ai/list-terms', 'ai/get-site-info', + 'ai/find-admin-screens', 'ai/propose-drafts', 'ai/propose-template', 'ai/propose-post-changes', @@ -156,14 +158,16 @@ public function tearDown(): void { Test_Update_Kind::unregister_ability(); $ability_names = array_merge( - array( 'ai/search-content', 'ai/read-content-bodies', 'ai/list-terms', 'ai/get-site-info', 'ai/propose-drafts', 'ai/propose-template', 'ai/propose-post-changes', 'ai/propose-site-identity', 'ai/ask-user', self::EDITOR_ABILITY ), + array( 'ai/search-content', 'ai/read-content-bodies', 'ai/list-terms', 'ai/get-site-info', 'ai/find-admin-screens', 'ai/propose-drafts', 'ai/propose-template', 'ai/propose-post-changes', 'ai/propose-site-identity', 'ai/ask-user', self::EDITOR_ABILITY ), $this->registered ); foreach ( $ability_names as $ability_name ) { - if ( wp_has_ability( $ability_name ) ) { - wp_unregister_ability( $ability_name ); + if ( ! wp_has_ability( $ability_name ) ) { + continue; } + + wp_unregister_ability( $ability_name ); } $this->registered = array(); @@ -173,14 +177,16 @@ public function tearDown(): void { foreach ( array( 'post', 'page' ) as $post_type ) { $object = get_post_type_object( $post_type ); - if ( $object ) { - // WordPress 7.2 declares the property, and unsetting a declared property leaves it - // uninitialized, so restore core's default rather than removing it. - if ( property_exists( \WP_Post_Type::class, 'show_in_abilities' ) ) { - $object->show_in_abilities = true; - } else { - unset( $object->show_in_abilities ); - } + if ( ! $object ) { + continue; + } + + // WordPress 7.2 declares the property, and unsetting a declared property leaves it + // uninitialized, so restore core's default rather than removing it. + if ( property_exists( \WP_Post_Type::class, 'show_in_abilities' ) ) { + $object->show_in_abilities = true; + } else { + unset( $object->show_in_abilities ); } } @@ -454,7 +460,7 @@ public function test_declared_readonly_ability_is_admitted(): void { 'wpai-test/declared-reader', array( self::DECLARATION_CHANNEL => array( 'public' => true ), - 'annotations' => $this->safe_annotations(), + 'annotations' => $this->safe_annotations(), ) ); @@ -505,7 +511,7 @@ public function test_declared_ability_with_wrong_effect_class_is_not_admitted( a $ability_id, array( self::DECLARATION_CHANNEL => array( 'public' => true ), - 'annotations' => $annotations, + 'annotations' => $annotations, ) ); @@ -600,7 +606,7 @@ public function test_policy_off_on_old_wordpress_returns_the_curated_surface(): 'wpai-test/declared-reader', array( self::DECLARATION_CHANNEL => array( 'public' => true ), - 'annotations' => $this->safe_annotations(), + 'annotations' => $this->safe_annotations(), ) ); @@ -636,7 +642,7 @@ public function test_kill_switch_returns_the_curated_surface(): void { 'wpai-test/declared-reader', array( self::DECLARATION_CHANNEL => array( 'public' => true ), - 'annotations' => $this->safe_annotations(), + 'annotations' => $this->safe_annotations(), ) ); @@ -672,7 +678,7 @@ public function test_candidates_filter_still_adds_and_removes(): void { 'wpai-test/declared-reader', array( self::DECLARATION_CHANNEL => array( 'public' => true ), - 'annotations' => $this->safe_annotations(), + 'annotations' => $this->safe_annotations(), ) ); $this->register_fixture( @@ -858,9 +864,11 @@ private function discovered_names(): array { $names = array(); foreach ( wp_get_abilities( ( new Tool_Policy() )->get_discovery_args() ) as $ability ) { - if ( $ability instanceof WP_Ability ) { - $names[] = $ability->get_name(); + if ( ! ( $ability instanceof WP_Ability ) ) { + continue; } + + $names[] = $ability->get_name(); } return $names; @@ -878,7 +886,7 @@ public function test_explorer_inventory_is_unchanged_by_the_policy(): void { 'wpai-test/declared-reader', array( self::DECLARATION_CHANNEL => array( 'public' => true ), - 'annotations' => $this->safe_annotations(), + 'annotations' => $this->safe_annotations(), ) ); $this->register_fixture( @@ -921,7 +929,7 @@ public function test_admission_is_off_until_the_declaration_is_public(): void { 'wpai-test/gated-reader', array( self::DECLARATION_CHANNEL => array( 'public' => true ), - 'annotations' => $this->safe_annotations(), + 'annotations' => $this->safe_annotations(), ) ); @@ -1014,9 +1022,11 @@ public function test_owner_removal_holds_without_the_workspace_bootstrap(): void * @since x.x.x */ private function require_filtered_discovery(): void { - if ( ! ( new Tool_Policy() )->supports_filtered_discovery() ) { - $this->markTestSkipped( 'This WordPress does not support filtered ability discovery.' ); + if ( ( new Tool_Policy() )->supports_filtered_discovery() ) { + return; } + + $this->markTestSkipped( 'This WordPress does not support filtered ability discovery.' ); } /** @@ -1049,9 +1059,11 @@ private function explorer_slugs(): array { $slugs = array(); foreach ( Ability_Handler::get_all_abilities() as $ability ) { - if ( isset( $ability['slug'] ) && is_string( $ability['slug'] ) ) { - $slugs[] = $ability['slug']; + if ( ! isset( $ability['slug'] ) || ! is_string( $ability['slug'] ) ) { + continue; } + + $slugs[] = $ability['slug']; } sort( $slugs ); @@ -1076,6 +1088,7 @@ private function use_curated_surface_only(): void { ( new Read_Content_Bodies() )->register(); ( new List_Terms() )->register(); ( new Get_Site_Info() )->register(); + ( new Find_Admin_Screens() )->register(); ( new Propose_Drafts() )->register(); ( new Propose_Template() )->register(); ( new Propose_Post_Changes() )->register(); @@ -1105,7 +1118,7 @@ private function use_curated_surface_only(): void { * * @since x.x.x * - * @return Tool_Selector The selector under test. + * @return \WordPress\AI\Experiments\AI_Workspace\Tool_Selector The selector under test. */ private function selector_without_filtered_discovery(): Tool_Selector { $policy = new class() extends Tool_Policy { @@ -1201,8 +1214,8 @@ public function test_built_in_kinds_keep_their_capabilities(): void { $this->assertSame( 'edit_posts', $candidates['ai/propose-post-changes'] ); $this->assertSame( 'manage_options', $candidates['ai/propose-site-identity'] ); $this->assertSame( - array( 'ai/search-content', 'ai/read-content-bodies', 'ai/list-terms', 'ai/get-site-info', 'ai/propose-drafts', 'ai/propose-template', 'ai/propose-post-changes', 'ai/propose-site-identity', 'ai/ask-user' ), - array_slice( array_keys( $candidates ), 0, 9 ) + array( 'ai/search-content', 'ai/read-content-bodies', 'ai/list-terms', 'ai/get-site-info', 'ai/find-admin-screens', 'ai/propose-drafts', 'ai/propose-template', 'ai/propose-post-changes', 'ai/propose-site-identity', 'ai/ask-user' ), + array_slice( array_keys( $candidates ), 0, 10 ) ); } diff --git a/tests/e2e-testing/responses/Anthropic/scenarios/workspace-navigate.json b/tests/e2e-testing/responses/Anthropic/scenarios/workspace-navigate.json new file mode 100644 index 000000000..20736e17e --- /dev/null +++ b/tests/e2e-testing/responses/Anthropic/scenarios/workspace-navigate.json @@ -0,0 +1,49 @@ +{ + "description": "A Site Context turn for \"Where do I change the timezone?\" that calls ai/find-admin-screens once, then answers with a link to the screen it returned. Entry 0 answers the first round, entry 1 the round that follows the tool response.", + "sequence": [ + { + "id": "msg_e2e_navigate_round_1", + "type": "message", + "role": "assistant", + "model": "claude-sonnet-5", + "content": [ + { + "type": "text", + "text": "Let me find the screen for that." + }, + { + "type": "tool_use", + "id": "toolu_e2e_navigate_1", + "name": "wpab__ai__find-admin-screens", + "input": { + "query": "change the timezone" + } + } + ], + "stop_reason": "tool_use", + "stop_sequence": null, + "usage": { + "input_tokens": 480, + "output_tokens": 40 + } + }, + { + "id": "msg_e2e_navigate_round_2", + "type": "message", + "role": "assistant", + "model": "claude-sonnet-5", + "content": [ + { + "type": "text", + "text": "You can change the timezone under [Settings → General](/wp-admin/options-general.php), in the Timezone field." + } + ], + "stop_reason": "end_turn", + "stop_sequence": null, + "usage": { + "input_tokens": 760, + "output_tokens": 30 + } + } + ] +} diff --git a/tests/e2e/specs/experiments/ai-workspace-navigate.spec.ts b/tests/e2e/specs/experiments/ai-workspace-navigate.spec.ts new file mode 100644 index 000000000..66305e4ad --- /dev/null +++ b/tests/e2e/specs/experiments/ai-workspace-navigate.spec.ts @@ -0,0 +1,86 @@ +/** + * End-to-end coverage for finding an admin screen from the AI Workspace. + * + * "Where do I change the timezone?" runs `ai/find-admin-screens`, and the + * answer links Settings → General. The link is on the site's own admin host, + * so the transcript renders it as a live anchor, and following it opens the + * screen. + */ +/** + * WordPress dependencies + */ +import { test, expect } from '@wordpress/e2e-test-utils-playwright'; + +/** + * Internal dependencies + */ +import { + activateMockScenario, + deactivateMockScenario, + disableExperiment, + enableExperiment, + getMockScenarioReport, + seedCredentials, +} from '../../utils/helpers'; + +const EXPERIMENT_LABEL = 'AI Workspace'; +const WORKSPACE_PAGE = 'tools.php?page=ai-workspace'; + +test.describe( 'AI Workspace navigation', () => { + test.beforeEach( async ( { admin, page, requestUtils } ) => { + await seedCredentials( requestUtils, [ 'anthropic' ] ); + await enableExperiment( admin, page, EXPERIMENT_LABEL ); + } ); + + test.afterEach( async ( { admin, page, requestUtils } ) => { + await deactivateMockScenario( requestUtils ); + await disableExperiment( admin, page, EXPERIMENT_LABEL ); + await seedCredentials( requestUtils, [ 'openai' ] ); + } ); + + test( 'asking where to change the timezone links Settings → General, and the link opens it', async ( { + admin, + page, + requestUtils, + } ) => { + await activateMockScenario( requestUtils, 'workspace-navigate' ); + await admin.visitAdminPage( WORKSPACE_PAGE ); + + await page + .getByLabel( 'Message', { exact: true } ) + .fill( 'Where do I change the timezone?' ); + await page.getByRole( 'button', { name: 'Send' } ).click(); + + const turn = page.locator( '.ai-workspace__turn' ).first(); + const link = turn.getByRole( 'link', { name: 'Settings → General' } ); + + await expect( link ).toBeVisible( { timeout: 30000 } ); + await expect( link ).toHaveAttribute( + 'href', + /\/wp-admin\/options-general\.php$/ + ); + + // The screen finder ran on the server and succeeded. + const tools = turn.locator( '.ai-workspace__tools' ); + await tools.locator( 'summary' ).click(); + await expect( tools.locator( 'code' ) ).toHaveText( + 'ai/find-admin-screens' + ); + await expect( tools ).toContainText( 'success' ); + + // Both fixture entries answered the turn: the tool round trip happened. + expect( + ( await getMockScenarioReport( requestUtils ) ).calls[ + 'Anthropic/workspace-navigate' + ] + ).toBe( 2 ); + + await link.click(); + + await expect( page ).toHaveURL( /\/wp-admin\/options-general\.php$/ ); + await expect( + page.getByRole( 'heading', { name: 'General Settings', level: 1 } ) + ).toBeVisible(); + await expect( page.getByLabel( 'Timezone' ) ).toBeVisible(); + } ); +} ); From 21cf902bea996f545683b6c9ce153a08971d8782 Mon Sep 17 00:00:00 2001 From: Jake Spurlock Date: Fri, 6 Nov 2026 18:31:07 -0800 Subject: [PATCH 3/8] fix(review): site info and screen finder fixes from code review Part of #1287 (PR B). Each was reproduced before fixing. - ai/get-site-info failed when called with no input ("input is not of type object"), which is how a model or MCP client calls an ability that takes none. The input schema now defaults to an empty object. - The site name and tagline came back HTML-escaped ("Tom & Jerry's"). They are now decoded, as the site identity card does. - The WordPress and PHP versions are gated on view_site_health_checks, core's Site Health capability, rather than manage_options. On multisite that keeps them to super admins, as core does. - The screen finder's stemmer turned "setting" into "sett" but "settings" into "setting", so a singular query missed plural keywords. The -ing rule is gone; every word in the map now stems the same way twice. - Tests for the block-theme branch: the Site Editor on block themes, the Customizer on classic ones. Co-Authored-By: Claude Opus 5.5 --- docs/experiments/ai-workspace.md | 6 +- .../Abilities/Site/Find_Admin_Screens.php | 8 +- includes/Abilities/Site/Get_Site_Info.php | 23 ++-- readme.txt | 2 +- .../Abilities/Site/Find_Admin_ScreensTest.php | 103 ++++++++++++++++++ .../Abilities/Site/Get_Site_InfoTest.php | 57 +++++++++- 6 files changed, 182 insertions(+), 17 deletions(-) diff --git a/docs/experiments/ai-workspace.md b/docs/experiments/ai-workspace.md index 4af71af01..ef7ce26be 100644 --- a/docs/experiments/ai-workspace.md +++ b/docs/experiments/ai-workspace.md @@ -54,7 +54,7 @@ The abilities offered to the model are not everything registered on the site. Th | `ai/search-content` | Full-text search over the post types exposed to abilities, or the newest posts when there is no search term, filterable by term, date range and featured image; returns titles, excerpts and terms | any authenticated user | | `ai/read-content-bodies` | Returns the full body text of up to five posts named by ID | any authenticated user | | `ai/list-terms` | Lists the site's categories, tags and other public terms with how many published posts each holds | any authenticated user | -| `ai/get-site-info` | Returns the site's name, tagline, home URL, language, timezone, date and time formats and active theme, with the WordPress and PHP versions for `manage_options` only | any authenticated user | +| `ai/get-site-info` | Returns the site's name, tagline, home URL, language, timezone, date and time formats and active theme, with the WordPress and PHP versions only for users who can `view_site_health_checks` | any authenticated user | | `ai/find-admin-screens` | Finds up to five admin screens for a short description of a task, such as "hide my site from google", from a curated map; returns only screens the user can open, each with its title, menu section and `admin_url()` link | any authenticated user | | `ai/propose-drafts` | Records a proposed set of drafts for a person to approve; writes nothing | `edit_posts` | | `ai/propose-template` | Records one proposed block template for a person to approve; writes nothing | `edit_theme_options` | @@ -188,7 +188,7 @@ Registered alongside `ai/search-content`. It lists the terms of publicly viewabl ### `ai/get-site-info` -Registered alongside `ai/search-content`, shown in REST, and listed over MCP by the MCP Adapter experiment like the other reads. It takes no input and returns a fixed set of fields: `name`, `tagline`, `home_url`, `language` (the site locale, such as `en_US`), `timezone` (a named zone, or a UTC offset such as `-05:00` when none is set), `date_format`, `time_format`, `theme` (the active theme's name) and `is_block_theme`. A user who can `manage_options` also gets `wp_version` and `php_version`; the output schema marks both optional, and an editor's response leaves them out rather than sending them empty. It needs only an authenticated user, like the other reads, because every other field is visible on the front end. +Registered alongside `ai/search-content`, shown in REST, and listed over MCP by the MCP Adapter experiment like the other reads. It takes no input and returns a fixed set of fields: `name`, `tagline`, `home_url`, `language` (the site locale, such as `en_US`), `timezone` (a named zone, or a UTC offset such as `-05:00` when none is set), `date_format`, `time_format`, `theme` (the active theme's name) and `is_block_theme`. A user who can `view_site_health_checks` also gets `wp_version` and `php_version`; the output schema marks both optional, and an editor's response leaves them out rather than sending them empty. That is core's Site Health meta capability, which shows the same versions; it maps to `install_plugins`, so on multisite only a super admin gets them, not a sub-site administrator who has `manage_options`. The name and tagline are returned as plain text, with the HTML entities WordPress stores them with decoded. Calling it with no input at all is the same as passing an empty object. It needs only an authenticated user, like the other reads, because every other field is visible on the front end. It never returns the admin email, the WordPress address (`siteurl`), database details or the plugin list. That is why it sits on the floor while `core/get-environment-info` and `core/settings-get` stay on the [withheld list](#wpai_workspace_withheld_abilities): two version strings for administrators are a narrow exception to that list's rationale, not a way around it. It is annotated read-only, not destructive, idempotent and not open-world, so it stays admissible if declaration-based admission is switched on. @@ -495,7 +495,7 @@ would be correct for core to add. The plugin's own `ai/get-site-info` is not on this list, although it reads site configuration: it returns a fixed field set with no admin email, no plugin list and no database details, and the WordPress and PHP versions only for -`manage_options`. +`view_site_health_checks`. Removing one is a deliberate act by someone with code access, which is the point: diff --git a/includes/Abilities/Site/Find_Admin_Screens.php b/includes/Abilities/Site/Find_Admin_Screens.php index df279c102..3c492a981 100644 --- a/includes/Abilities/Site/Find_Admin_Screens.php +++ b/includes/Abilities/Site/Find_Admin_Screens.php @@ -395,6 +395,10 @@ private function tokenize( string $text ): array { /** * Reduces a word to a rough stem, so "comments" matches "comment". * + * Only plurals are folded. The result never ends in a further plural, so + * stemming a stem returns it unchanged and "setting" meets "settings". There + * is no "-ing" rule: it took "setting" to "sett" but "settings" only to "setting". + * * @since x.x.x * * @param string $word A lowercase word. @@ -407,10 +411,6 @@ private function stem( string $word ): string { return substr( $word, 0, -3 ) . 'y'; } - if ( $length > 5 && 'ing' === substr( $word, -3 ) ) { - return substr( $word, 0, -3 ); - } - if ( $length > 3 && 's' === substr( $word, -1 ) && 'ss' !== substr( $word, -2 ) ) { return substr( $word, 0, -1 ); } diff --git a/includes/Abilities/Site/Get_Site_Info.php b/includes/Abilities/Site/Get_Site_Info.php index b9cc8079e..92ac7d294 100644 --- a/includes/Abilities/Site/Get_Site_Info.php +++ b/includes/Abilities/Site/Get_Site_Info.php @@ -26,7 +26,9 @@ * The name, tagline, home URL, language and theme are visible on the front end, and * the timezone and formats shape every date the site prints, so the ability requires * only an authenticated user, like the other workspace reads. The WordPress and - * PHP versions are added only for a user who can `manage_options`. + * PHP versions are added only for a user who can `view_site_health_checks`, the + * meta capability core uses for Site Health, which shows the same versions. It + * maps to `install_plugins`, so on multisite only a super admin gets them. * * It never returns the admin email, the WordPress address (`siteurl`), database * details or the plugin list, which is what keeps it narrower than @@ -71,12 +73,14 @@ public function register(): void { self::ABILITY, array( 'label' => __( 'Get Site Info', 'ai' ), - 'description' => __( 'Returns facts about this site: its name, tagline, home URL, language, timezone, date and time formats, active theme and whether it is a block theme. The WordPress and PHP versions are included only for administrators. Takes no input. Requires an authenticated user.', 'ai' ), + 'description' => __( 'Returns facts about this site: its name, tagline, home URL, language, timezone, date and time formats, active theme and whether it is a block theme. The WordPress and PHP versions are included only for users who can view Site Health. Takes no input. Requires an authenticated user.', 'ai' ), 'category' => WPAI_DEFAULT_ABILITY_CATEGORY, 'input_schema' => array( 'type' => 'object', 'additionalProperties' => false, 'properties' => array(), + // Lets the ability run with no input at all, as `core/get-site-info` does. + 'default' => array(), ), 'output_schema' => $this->get_output_schema(), 'execute_callback' => array( $this, 'execute_get_site_info' ), @@ -121,8 +125,9 @@ public function execute_get_site_info( $input = array() ): array { unset( $input ); $info = array( - 'name' => (string) get_bloginfo( 'name' ), - 'tagline' => (string) get_bloginfo( 'description' ), + // Stored HTML-escaped; decoded as the Settings screen shows them. + 'name' => wp_specialchars_decode( (string) get_bloginfo( 'name' ), ENT_QUOTES ), + 'tagline' => wp_specialchars_decode( (string) get_bloginfo( 'description' ), ENT_QUOTES ), 'home_url' => (string) home_url( '/' ), 'language' => (string) get_locale(), // A named zone, or the UTC offset such as `-05:00` when none is set. @@ -133,8 +138,10 @@ public function execute_get_site_info( $input = array() ): array { 'is_block_theme' => wp_is_block_theme(), ); - // Versions say which known vulnerabilities apply, so only administrators get them. - if ( current_user_can( 'manage_options' ) ) { + // Versions say which known vulnerabilities apply, so only a user who can see + // them in Site Health gets them. On multisite that is a super admin, not a + // sub-site administrator who has `manage_options`. + if ( current_user_can( 'view_site_health_checks' ) ) { $info['wp_version'] = (string) get_bloginfo( 'version' ); $info['php_version'] = PHP_VERSION; } @@ -194,11 +201,11 @@ private function get_output_schema(): array { ), 'wp_version' => array( 'type' => 'string', - 'description' => __( 'The WordPress version. Present only for administrators.', 'ai' ), + 'description' => __( 'The WordPress version. Present only for users who can view Site Health.', 'ai' ), ), 'php_version' => array( 'type' => 'string', - 'description' => __( 'The PHP version. Present only for administrators.', 'ai' ), + 'description' => __( 'The PHP version. Present only for users who can view Site Health.', 'ai' ), ), ), ); diff --git a/readme.txt b/readme.txt index 740c7faa5..e1848de72 100644 --- a/readme.txt +++ b/readme.txt @@ -233,7 +233,7 @@ Go to `Plugins` and deactivate AI. If you can't reach the admin, deactivate it w - New Experiment: AI Workspace; a dedicated `Tools -> AI Workspace` screen where you hold a multi-step, site-aware conversation with an assistant. The assistant can search your content under your own capabilities, renders post results as a table, and writes nothing until you approve a proposal, which shows the exact values -- including the post status -- that will be written ([#282](https://github.com/WordPress/ai/issues/282)). - New `ai/search-content` Ability that runs a bounded, capability-filtered full-text search across the post types exposed to abilities, returning titles and excerpts rather than post bodies ([#282](https://github.com/WordPress/ai/issues/282)). -- New `ai/get-site-info` Ability that returns the site's name, tagline, home URL, language, timezone, date and time formats, active theme and whether it is a block theme, plus the WordPress and PHP versions for users who can `manage_options`. It never returns the admin email, the WordPress address, database details or the plugin list, which is why the AI Workspace offers it while withholding the broad `core/get-environment-info` and `core/settings-get` ([#1287](https://github.com/WordPress/ai/issues/1287)). +- New `ai/get-site-info` Ability that returns the site's name, tagline, home URL, language, timezone, date and time formats, active theme and whether it is a block theme, plus the WordPress and PHP versions for users who can view Site Health (`view_site_health_checks`). It never returns the admin email, the WordPress address, database details or the plugin list, which is why the AI Workspace offers it while withholding the broad `core/get-environment-info` and `core/settings-get` ([#1287](https://github.com/WordPress/ai/issues/1287)). - New `ai/find-admin-screens` Ability that answers "where do I…" with links: given a short description such as "hide my site from google", it returns up to five matching admin screens from a curated map of core screens, only those the current user can open, each linked with `admin_url()`. Matching runs on the server with no model call, and the map is filterable through `wpai_admin_screens` ([#1287](https://github.com/WordPress/ai/issues/1287)). - The AI Workspace's tool surface is no longer a fixed list. An ability exposed to the surface - through `meta.public`, or by naming the `ai-workspace` channel - and annotated `readonly: true`, `destructive: false`, `open_world: false` - can be offered to the assistant alongside the three that ship with it. Admission defaults to refusing: an ability that is not public, and has not opted in, is never offered. Declaration-based admission is itself switched **off** until [#354](https://github.com/WordPress/ai/issues/354) settles the channel name, so the shipped surface is still the three curated abilities; `add_filter( 'wpai_workspace_tool_admission_enabled', '__return_true' )`, or the `WPAI_WORKSPACE_TOOL_ADMISSION` constant, turns it on to try it. A short list of core abilities that read personal data, settings or environment detail is never admitted whatever they declare, filterable through `wpai_workspace_withheld_abilities`. Exposure and the annotations are both the ability author's self-attestation, and the effect class is a declared intent rather than an enforced property: the site owner's Explorer controls and the execute-time `permission_callback` remain the boundaries ([#1003](https://github.com/WordPress/ai/issues/1003)). - The Abilities Explorer shows which abilities the AI Workspace assistant can call, the exact description text the model receives, and why any other ability is excluded. A site owner can remove an ability from the surface or switch the policy off entirely and return to the three that ship ([#1003](https://github.com/WordPress/ai/issues/1003)). diff --git a/tests/Integration/Includes/Abilities/Site/Find_Admin_ScreensTest.php b/tests/Integration/Includes/Abilities/Site/Find_Admin_ScreensTest.php index 37c71c13d..2b65e5577 100644 --- a/tests/Integration/Includes/Abilities/Site/Find_Admin_ScreensTest.php +++ b/tests/Integration/Includes/Abilities/Site/Find_Admin_ScreensTest.php @@ -45,6 +45,15 @@ class Find_Admin_ScreensTest extends WP_UnitTestCase { */ private static $user_ids = array(); + /** + * The stylesheet active before a test switched themes. + * + * @since x.x.x + * + * @var string|null + */ + private $original_theme = null; + /** * Creates the shared users. * @@ -78,6 +87,11 @@ public function setUp(): void { */ public function tearDown(): void { remove_all_filters( 'wpai_admin_screens' ); + + if ( null !== $this->original_theme && get_stylesheet() !== $this->original_theme ) { + switch_theme( $this->original_theme ); + } + remove_filter( 'wp_register_ability_args', array( Exposure_Overrides::class, 'filter_ability_args' ), 100 ); if ( wp_has_ability( Find_Admin_Screens::ABILITY ) ) { @@ -171,6 +185,95 @@ public function test_changing_the_timezone_finds_general_settings_first(): void $this->assertSame( admin_url( 'options-general.php' ), $urls[0] ); } + /** + * "setting" and "settings" are the same word, so both find Settings, General first for "general setting(s)". + * + * @since x.x.x + */ + public function test_singular_and_plural_settings_match_alike(): void { + $general = admin_url( 'options-general.php' ); + $plural = $this->urls( $this->find_as( 'administrator', 'general settings' ) ); + + $this->assertSame( $general, $plural[0] ); + $this->assertSame( $plural, $this->urls( $this->find_as( 'administrator', 'general setting' ) ) ); + $this->assertContains( $general, $this->urls( $this->find_as( 'administrator', 'setting' ) ) ); + } + + /** + * Stemming is idempotent for every word in the screen map, so a stemmed word always meets its own stem. + * + * @since x.x.x + */ + public function test_stem_is_idempotent_for_every_word_in_the_map(): void { + $finder = new Find_Admin_Screens(); + $stem = new \ReflectionMethod( $finder, 'stem' ); + $stem->setAccessible( true ); + + $words = array(); + + foreach ( require WPAI_PLUGIN_DIR . 'includes/Abilities/Site/admin-screens.php' as $screen ) { + $text = implode( ' ', array_merge( array( $screen['title'], $screen['section'] ?? '' ), $screen['keywords'] ) ); + $text = strtolower( $text ); + + foreach ( (array) preg_split( '/[^\p{L}\p{N}]+/u', $text, -1, PREG_SPLIT_NO_EMPTY ) as $word ) { + $words[] = (string) $word; + $words[] = $word . 's'; + } + } + + $this->assertNotEmpty( $words ); + + foreach ( array_unique( $words ) as $word ) { + $once = $stem->invoke( $finder, $word ); + + $this->assertSame( $once, $stem->invoke( $finder, $once ), $word ); + } + } + + /** + * On a block theme, "customize colors" finds the Site Editor and never the Customizer. + * + * @since x.x.x + */ + public function test_block_theme_offers_the_site_editor_not_the_customizer(): void { + $this->switch_to( 'twentytwentyfive' ); + $this->assertTrue( wp_is_block_theme() ); + + $urls = $this->urls( $this->find_as( 'administrator', 'customize colors' ) ); + + $this->assertContains( admin_url( 'site-editor.php' ), $urls ); + $this->assertNotContains( admin_url( 'customize.php' ), $urls ); + } + + /** + * On a classic theme, "customize colors" finds the Customizer and never the Site Editor. + * + * @since x.x.x + */ + public function test_classic_theme_offers_the_customizer_not_the_site_editor(): void { + $this->switch_to( 'twentytwentyone' ); + $this->assertFalse( wp_is_block_theme() ); + + $urls = $this->urls( $this->find_as( 'administrator', 'customize colors' ) ); + + $this->assertContains( admin_url( 'customize.php' ), $urls ); + $this->assertNotContains( admin_url( 'site-editor.php' ), $urls ); + } + + /** + * Switches to a theme for one test, remembering the original for tearDown(). + * + * @since x.x.x + * + * @param string $stylesheet The theme to activate. + */ + private function switch_to( string $stylesheet ): void { + $this->assertTrue( wp_get_theme( $stylesheet )->exists(), $stylesheet . ' must be installed.' ); + + $this->original_theme = get_stylesheet(); + switch_theme( $stylesheet ); + } + /** * No more than five screens come back. * diff --git a/tests/Integration/Includes/Abilities/Site/Get_Site_InfoTest.php b/tests/Integration/Includes/Abilities/Site/Get_Site_InfoTest.php index c3499c4b9..aace49b25 100644 --- a/tests/Integration/Includes/Abilities/Site/Get_Site_InfoTest.php +++ b/tests/Integration/Includes/Abilities/Site/Get_Site_InfoTest.php @@ -46,7 +46,7 @@ class Get_Site_InfoTest extends WP_UnitTestCase { ); /** - * The fields only a user who can `manage_options` gets. + * The fields only a user who can `view_site_health_checks` gets. * * @since x.x.x * @@ -166,6 +166,61 @@ public function test_administrator_gets_every_field_including_versions(): void { $this->assertSame( PHP_VERSION, $result['php_version'] ); } + /** + * The ability runs when called with no input at all, as core's own `core/get-site-info` does. + * + * @since x.x.x + */ + public function test_executes_without_any_input(): void { + wp_set_current_user( self::$user_ids['editor'] ); + + $result = wp_get_ability( Get_Site_Info::ABILITY )->execute(); + + $this->assertIsArray( $result ); + $this->assertSame( self::SHARED_FIELDS, array_keys( $result ) ); + } + + /** + * The name and tagline come back as plain text, not with the HTML entities they are stored with. + * + * @since x.x.x + */ + public function test_name_and_tagline_are_decoded(): void { + update_option( 'blogname', "Tom & Jerry's" ); + update_option( 'blogdescription', "Cats & mice, \"chased\" since '40" ); + + $result = $this->run_as( 'editor' ); + + $this->assertSame( "Tom & Jerry's", $result['name'] ); + $this->assertSame( "Cats & mice, \"chased\" since '40", $result['tagline'] ); + } + + /** + * A user with `manage_options` but not `view_site_health_checks`, such as a sub-site + * administrator on multisite, gets no versions. + * + * @since x.x.x + */ + public function test_manage_options_without_site_health_access_gets_no_versions(): void { + $deny = static function ( array $caps, string $cap ): array { + return 'view_site_health_checks' === $cap ? array( 'do_not_allow' ) : $caps; + }; + add_filter( 'map_meta_cap', $deny, 10, 2 ); + + try { + wp_set_current_user( self::$user_ids['administrator'] ); + $this->assertTrue( current_user_can( 'manage_options' ) ); + $this->assertFalse( current_user_can( 'view_site_health_checks' ) ); + + $result = wp_get_ability( Get_Site_Info::ABILITY )->execute( array() ); + } finally { + remove_filter( 'map_meta_cap', $deny, 10 ); + } + + $this->assertIsArray( $result ); + $this->assertSame( self::SHARED_FIELDS, array_keys( $result ) ); + } + /** * A site set to a UTC offset rather than a named zone reports the offset. * From d97e532766bd957499ce69be7c735363bf0702a9 Mon Sep 17 00:00:00 2001 From: Jake Spurlock Date: Fri, 6 Nov 2026 18:41:34 -0800 Subject: [PATCH 4/8] test(ai-workspace): use a fixture classic theme for the Customizer test The classic-theme screen-finder test switched to Twenty Twenty-One, which the CI environment doesn't install, so it failed there while passing locally. It now registers a minimal classic theme under tests/Integration/fixtures/themes and restores the theme directories afterwards. Co-Authored-By: Claude Opus 5.5 --- .../Abilities/Site/Find_Admin_ScreensTest.php | 23 ++++++++++++++++++- .../themes/wpai-classic-fixture/index.php | 6 +++++ .../themes/wpai-classic-fixture/style.css | 5 ++++ 3 files changed, 33 insertions(+), 1 deletion(-) create mode 100644 tests/Integration/fixtures/themes/wpai-classic-fixture/index.php create mode 100644 tests/Integration/fixtures/themes/wpai-classic-fixture/style.css diff --git a/tests/Integration/Includes/Abilities/Site/Find_Admin_ScreensTest.php b/tests/Integration/Includes/Abilities/Site/Find_Admin_ScreensTest.php index 2b65e5577..5108353ff 100644 --- a/tests/Integration/Includes/Abilities/Site/Find_Admin_ScreensTest.php +++ b/tests/Integration/Includes/Abilities/Site/Find_Admin_ScreensTest.php @@ -54,6 +54,15 @@ class Find_Admin_ScreensTest extends WP_UnitTestCase { */ private $original_theme = null; + /** + * The theme directories before a test registered the fixture one. + * + * @since x.x.x + * + * @var list|null + */ + private $original_theme_directories = null; + /** * Creates the shared users. * @@ -92,6 +101,12 @@ public function tearDown(): void { switch_theme( $this->original_theme ); } + if ( null !== $this->original_theme_directories ) { + $GLOBALS['wp_theme_directories'] = $this->original_theme_directories; // phpcs:ignore WordPress.WP.GlobalVariablesOverride.Prohibited -- Restoring what the test changed. + search_theme_directories( true ); + wp_clean_themes_cache(); + } + remove_filter( 'wp_register_ability_args', array( Exposure_Overrides::class, 'filter_ability_args' ), 100 ); if ( wp_has_ability( Find_Admin_Screens::ABILITY ) ) { @@ -251,7 +266,13 @@ public function test_block_theme_offers_the_site_editor_not_the_customizer(): vo * @since x.x.x */ public function test_classic_theme_offers_the_customizer_not_the_site_editor(): void { - $this->switch_to( 'twentytwentyone' ); + // A fixture theme, so the test doesn't depend on which default themes the environment installs. + $this->original_theme_directories = $GLOBALS['wp_theme_directories']; + register_theme_directory( dirname( __DIR__, 3 ) . '/fixtures/themes' ); + search_theme_directories( true ); + wp_clean_themes_cache(); + + $this->switch_to( 'wpai-classic-fixture' ); $this->assertFalse( wp_is_block_theme() ); $urls = $this->urls( $this->find_as( 'administrator', 'customize colors' ) ); diff --git a/tests/Integration/fixtures/themes/wpai-classic-fixture/index.php b/tests/Integration/fixtures/themes/wpai-classic-fixture/index.php new file mode 100644 index 000000000..0ee6b5639 --- /dev/null +++ b/tests/Integration/fixtures/themes/wpai-classic-fixture/index.php @@ -0,0 +1,6 @@ + Date: Fri, 6 Nov 2026 18:51:52 -0800 Subject: [PATCH 5/8] test(ai-workspace): make the site ability tests pass on multisite On multisite only a super admin can open Plugins or see Site Health, as in core, so the administrator fixture in both test classes is now granted super admin there and revoked afterwards. The filter test used that administrator as the user without the custom capability; a super admin has every capability, so it uses the subscriber instead. Co-Authored-By: Claude Opus 5.5 --- .../Abilities/Site/Find_Admin_ScreensTest.php | 24 +++++++++++++++++-- .../Abilities/Site/Get_Site_InfoTest.php | 20 ++++++++++++++++ 2 files changed, 42 insertions(+), 2 deletions(-) diff --git a/tests/Integration/Includes/Abilities/Site/Find_Admin_ScreensTest.php b/tests/Integration/Includes/Abilities/Site/Find_Admin_ScreensTest.php index 5108353ff..14f67aabe 100644 --- a/tests/Integration/Includes/Abilities/Site/Find_Admin_ScreensTest.php +++ b/tests/Integration/Includes/Abilities/Site/Find_Admin_ScreensTest.php @@ -76,6 +76,26 @@ public static function wpSetUpBeforeClass( $factory ): void { 'editor' => $factory->user->create( array( 'role' => 'editor' ) ), 'subscriber' => $factory->user->create( array( 'role' => 'subscriber' ) ), ); + + // On multisite only a super admin can open Plugins or Site Health, as in core. + if ( ! is_multisite() ) { + return; + } + + grant_super_admin( self::$user_ids['administrator'] ); + } + + /** + * Revokes the super admin granted on multisite. + * + * @since x.x.x + */ + public static function wpTearDownAfterClass(): void { + if ( ! is_multisite() ) { + return; + } + + revoke_super_admin( self::$user_ids['administrator'] ); } /** @@ -345,14 +365,14 @@ static function ( array $screens ): array { $gizmo = admin_url( 'admin.php?page=gizmo' ); - $this->assertNotContains( $gizmo, $this->urls( $this->find_as( 'administrator', 'gizmo' ) ) ); + $this->assertNotContains( $gizmo, $this->urls( $this->find_as( 'subscriber', 'gizmo' ) ) ); $editor = get_user_by( 'id', self::$user_ids['editor'] ); $editor->add_cap( self::CUSTOM_CAP ); try { $this->assertSame( $gizmo, $this->urls( $this->find_as( 'editor', 'gizmo' ) )[0] ); - $this->assertNotContains( $gizmo, $this->urls( $this->find_as( 'administrator', 'gizmo' ) ) ); + $this->assertNotContains( $gizmo, $this->urls( $this->find_as( 'subscriber', 'gizmo' ) ) ); } finally { $editor->remove_cap( self::CUSTOM_CAP ); } diff --git a/tests/Integration/Includes/Abilities/Site/Get_Site_InfoTest.php b/tests/Integration/Includes/Abilities/Site/Get_Site_InfoTest.php index aace49b25..3ac4646f7 100644 --- a/tests/Integration/Includes/Abilities/Site/Get_Site_InfoTest.php +++ b/tests/Integration/Includes/Abilities/Site/Get_Site_InfoTest.php @@ -76,6 +76,26 @@ public static function wpSetUpBeforeClass( $factory ): void { 'editor' => $factory->user->create( array( 'role' => 'editor' ) ), 'subscriber' => $factory->user->create( array( 'role' => 'subscriber' ) ), ); + + // On multisite only a super admin can open Plugins or Site Health, as in core. + if ( ! is_multisite() ) { + return; + } + + grant_super_admin( self::$user_ids['administrator'] ); + } + + /** + * Revokes the super admin granted on multisite. + * + * @since x.x.x + */ + public static function wpTearDownAfterClass(): void { + if ( ! is_multisite() ) { + return; + } + + revoke_super_admin( self::$user_ids['administrator'] ); } /** From e9e32920535678c1924383cf4689787bcc4a73d2 Mon Sep 17 00:00:00 2001 From: Jake Spurlock Date: Fri, 6 Nov 2026 19:03:44 -0800 Subject: [PATCH 6/8] test: leave the admin screen map out of coverage admin-screens.php is a data map that Find_Admin_Screens loads. Its test class @covers that class, so PHPUnit drops the map's lines and Codecov reported the file at 0% (214 of the PR's 221 missing lines), though every entry runs on each call. It is now excluded, as the vendored code is. Co-Authored-By: Claude Opus 5.5 --- phpunit.xml.dist | 2 ++ 1 file changed, 2 insertions(+) diff --git a/phpunit.xml.dist b/phpunit.xml.dist index 30ef073f4..3e802d9be 100644 --- a/phpunit.xml.dist +++ b/phpunit.xml.dist @@ -23,8 +23,10 @@ includes + includes/Vendor + includes/Abilities/Site/admin-screens.php From 88ce16d6f5743102c34cb1f756c673959718769c Mon Sep 17 00:00:00 2001 From: Jake Spurlock Date: Fri, 6 Nov 2026 21:33:39 -0800 Subject: [PATCH 7/8] fix(ai-workspace): name tool steps neutrally when they aren't a search A tool step with no retrieval summary was labelled "Looked up site content", which was accurate when every tool read content. Finding an admin screen or reading site info isn't that, so the fallback now reads "Checked the site (1 step)". Co-Authored-By: Claude Opus 5.5 --- src/experiments/ai-workspace/components/Transcript.tsx | 4 ++-- tests/e2e/specs/experiments/ai-workspace-navigate.spec.ts | 4 ++++ tests/e2e/specs/experiments/ai-workspace-tools.spec.ts | 2 +- 3 files changed, 7 insertions(+), 3 deletions(-) diff --git a/src/experiments/ai-workspace/components/Transcript.tsx b/src/experiments/ai-workspace/components/Transcript.tsx index c6927502e..84cc922b8 100644 --- a/src/experiments/ai-workspace/components/Transcript.tsx +++ b/src/experiments/ai-workspace/components/Transcript.tsx @@ -260,8 +260,8 @@ function ToolSteps( { toolCalls }: { toolCalls: ToolCallRecord[] } ) { sprintf( /* translators: %d: number of tool calls. */ _n( - 'Looked up site content (%d step)', - 'Looked up site content (%d steps)', + 'Checked the site (%d step)', + 'Checked the site (%d steps)', toolCalls.length, 'ai' ), diff --git a/tests/e2e/specs/experiments/ai-workspace-navigate.spec.ts b/tests/e2e/specs/experiments/ai-workspace-navigate.spec.ts index 66305e4ad..a1ad08dfe 100644 --- a/tests/e2e/specs/experiments/ai-workspace-navigate.spec.ts +++ b/tests/e2e/specs/experiments/ai-workspace-navigate.spec.ts @@ -62,6 +62,10 @@ test.describe( 'AI Workspace navigation', () => { // The screen finder ran on the server and succeeded. const tools = turn.locator( '.ai-workspace__tools' ); + // Finding a screen isn't a content lookup, so the summary says so plainly. + await expect( tools.locator( 'summary' ) ).toHaveText( + 'Checked the site (1 step)' + ); await tools.locator( 'summary' ).click(); await expect( tools.locator( 'code' ) ).toHaveText( 'ai/find-admin-screens' diff --git a/tests/e2e/specs/experiments/ai-workspace-tools.spec.ts b/tests/e2e/specs/experiments/ai-workspace-tools.spec.ts index 974b2767f..a36ec1475 100644 --- a/tests/e2e/specs/experiments/ai-workspace-tools.spec.ts +++ b/tests/e2e/specs/experiments/ai-workspace-tools.spec.ts @@ -87,7 +87,7 @@ test.describe( 'AI Workspace tool loop', () => { // the whole path -- ability, turn response, transcript -- carried it. await expect( tools.locator( 'summary' ) ).toContainText( 'Searched' ); await expect( tools.locator( 'summary' ) ).not.toContainText( - 'Looked up site content' + 'Checked the site' ); /* From d9f3bb23253810f5ede9bfbd9870c27668758ccb Mon Sep 17 00:00:00 2001 From: Jake Spurlock Date: Mon, 9 Nov 2026 23:01:45 -0800 Subject: [PATCH 8/8] fix(abilities): send ai/get-site-info's input schema without an empty list The input schema declared `'properties' => array()`, which reaches the model as `"properties": []`. OpenAI refuses the request ("[] is not of type 'object'"), and because the workspace offers this ability on every turn, every message failed. Anthropic accepts the list, which is why the earlier live checks passed. The key is dropped. `additionalProperties: false` still refuses any input, and the empty default still lets it run with none. Co-Authored-By: Claude Opus 5.5 --- includes/Abilities/Site/Get_Site_Info.php | 7 ++++- .../Abilities/Site/Get_Site_InfoTest.php | 31 +++++++++++++++++++ 2 files changed, 37 insertions(+), 1 deletion(-) diff --git a/includes/Abilities/Site/Get_Site_Info.php b/includes/Abilities/Site/Get_Site_Info.php index 92ac7d294..20a1fd416 100644 --- a/includes/Abilities/Site/Get_Site_Info.php +++ b/includes/Abilities/Site/Get_Site_Info.php @@ -77,8 +77,13 @@ public function register(): void { 'category' => WPAI_DEFAULT_ABILITY_CATEGORY, 'input_schema' => array( 'type' => 'object', + /* + * No `properties` key: an empty one is sent to the model as + * `"properties": []`, and OpenAI refuses the whole request + * because `[]` is not an object. `additionalProperties` + * already refuses any input. + */ 'additionalProperties' => false, - 'properties' => array(), // Lets the ability run with no input at all, as `core/get-site-info` does. 'default' => array(), ), diff --git a/tests/Integration/Includes/Abilities/Site/Get_Site_InfoTest.php b/tests/Integration/Includes/Abilities/Site/Get_Site_InfoTest.php index 3ac4646f7..d3b25d3ff 100644 --- a/tests/Integration/Includes/Abilities/Site/Get_Site_InfoTest.php +++ b/tests/Integration/Includes/Abilities/Site/Get_Site_InfoTest.php @@ -307,6 +307,37 @@ public function test_logged_out_visitor_is_refused(): void { $this->assertWPError( wp_get_ability( Get_Site_Info::ABILITY )->execute( array() ) ); } + /** + * The input schema, as declared to the model, holds no empty list where + * JSON Schema expects an object. OpenAI refused every request that offered + * this ability while it sent `"properties": []`. + * + * @since x.x.x + */ + public function test_input_schema_declared_to_the_model_has_no_empty_list(): void { + $schema = wp_get_ability( Get_Site_Info::ABILITY )->get_input_schema(); + + if ( function_exists( 'wp_prepare_json_schema_for_client' ) ) { + $schema = wp_prepare_json_schema_for_client( $schema ); + } + + $this->assertStringNotContainsString( '"properties":[]', (string) wp_json_encode( $schema ) ); + } + + /** + * Input is still refused, with no properties declared. + * + * @since x.x.x + */ + public function test_refuses_any_input(): void { + wp_set_current_user( self::$user_ids['editor'] ); + + $result = wp_get_ability( Get_Site_Info::ABILITY )->execute( array( 'fields' => array( 'name' ) ) ); + + $this->assertWPError( $result ); + $this->assertSame( 'ability_invalid_input', $result->get_error_code() ); + } + /** * The output schema requires the shared fields and leaves the versions optional. *