'wp-abilities', 'title' => 'WordPress Abilities API', 'available' => self::is_available(), ); } /** * Project the abilities registry into discovery resources (one per namespace). * * @param Registry $registry The collector. */ public function provide( Registry $registry ) { // Inline guard (not just self::is_available()) so static analysis can see // that wp_get_abilities() — a WP 6.9+ API — is never called on older cores; // the plugin's baseline (llms/schema/robots/discovery) supports 6.3+. if ( ! function_exists( 'wp_get_abilities' ) ) { return; } $by_namespace = array(); foreach ( (array) wp_get_abilities() as $ability ) { $name = (string) self::read( $ability, 'get_name' ); if ( '' === $name ) { continue; } /** * Gate which abilities are advertised in the public discovery doc. * Discovery exposes tool *signatures*, not execution — but a site may * still wish to hide that a sensitive operation exists. * * @param bool $discoverable Default true. * @param string $name Ability name (e.g. "core/get-site-info"). * @param mixed $ability The ability object. */ if ( ! apply_filters( 'agentimus_discoverable_ability', true, $name, $ability ) ) { continue; } // An ability registered with `show_in_rest => false` has NO REST route at all — // it is not in the wp-abilities listing and cannot be run remotely by ANY agent // (it is an in-process PHP helper, e.g. core/get-user-info). Counting it as an // agent tool overcounted every surface at once: the namespace card, the tiles' // site-wide total and the Abilities API row all promised one more tool than the // endpoint they point at can ever serve. $meta = (array) self::read( $ability, 'get_meta', array() ); if ( isset( $meta['show_in_rest'] ) && false === $meta['show_in_rest'] ) { continue; } $namespace = strpos( $name, '/' ) ? substr( $name, 0, strpos( $name, '/' ) ) : 'misc'; $by_namespace[ $namespace ][] = array( 'name' => $name, 'ability' => $ability ); } // The owner's one veto, read once: keep every job that CHANGES something // out of the public documents, whatever its plugin marked. Publication is // the vendor's call; this is the owner's no on top of it, and on their own // site their no wins — the rule post_types_vetoed already states. $hold_back = (bool) ( new \Agentimus\Settings() )->get( 'hold_back_changing_jobs', false ); foreach ( $by_namespace as $namespace => $items ) { $registry->register( $this->resource_for( $namespace, $items, $hold_back ) ); } } /** * Build one discovery resource for a namespace's abilities. * * @param string $namespace Namespace slug. * @param array[] $items Each {name, ability}. * @param bool $hold_back The owner's veto on jobs that change something. * @return array */ private function resource_for( $namespace, $items, $hold_back = false ) { $tools = array(); $abilities = array(); $skills = array(); $needs_auth = false; $any_advertised = false; foreach ( $items as $item ) { $ability = $item['ability']; $name = $item['name']; $short = strpos( $name, '/' ) ? substr( $name, strpos( $name, '/' ) + 1 ) : $name; $desc = (string) self::read( $ability, 'get_description' ); // TWO SEPARATE QUESTIONS, and conflating them was the bug. // // 1. Does the vendor advertise this tool? Their call, never ours — // we neither publish what they kept back nor hide what they // published. That is the `mcp.public` mark, and nothing else. // 2. What does running it take? Ours to state honestly. A tool that // CHANGES something is never "no sign-in needed", whoever marked // it public: WooCommerce marks product-delete public, which asks // us to advertise it, not to promise anyone may run it. $read_only = self::read_only_hint( $ability, $name ); $advertised = self::advertised( $ability ) && ! ( $hold_back && ! $read_only ); $auth = self::auth_for(); // Only what is actually served decides the group's own line. if ( $advertised ) { $any_advertised = true; $needs_auth = $needs_auth || 'none' !== $auth; $abilities[] = $name; } $tools[] = array( 'name' => $name, // An ability carrying an MCP `uri` is a RESOURCE — a document an // assistant attaches, not a tool it runs. MCP itself keeps the two // apart (tools/list vs resources/list) and so does our own README, // but this array flattened them, so every count downstream said // "tools" for a number that included four documents. 'kind' => self::is_resource( $ability ) ? 'resource' : 'tool', // The vendor's decision, carried per tool so a namespace with a // mixed hand publishes exactly the hand it was dealt. Held-back // tools still reach the ADMIN screen — the owner sees everything // their site holds; only the served document is trimmed. 'public' => $advertised, 'title' => (string) self::read( $ability, 'get_label' ), 'description' => $desc, 'inputSchema' => (array) self::read( $ability, 'get_input_schema', array() ), 'outputSchema' => (array) self::read( $ability, 'get_output_schema', array() ), 'annotations' => array( 'readOnlyHint' => self::read_only_hint( $ability, $name ) ), 'auth' => $auth, // Resources only: the public address the document lives at, so the // admin can link the row to the file itself. '' for runnable tools. 'uri' => self::resource_uri( $ability ), ); $skills[] = array( 'id' => sanitize_key( $short ), 'description' => '' !== $desc ? $desc : (string) self::read( $ability, 'get_label' ) ); } /** * Whether to publish abilities that NOBODY anonymous can call. * * Default FALSE, and this is the deliberate position. Every ability here is gated behind a * capability check, so an anonymous agent can never invoke one — publishing them to the * anonymous discovery document gives that agent nothing it can use, while handing anyone who * asks a complete map of the site's tooling: each tool's name, its LLM-facing description * and its full input/output schemas. `agentimus/scan-exposed-files`, for instance, described * in public exactly which sensitive paths the site probes for. * * It also contradicted our own {@see \Agentimus\Abilities\Registrar}, which sets * `mcp.public => false` on every ability precisely to keep them off a public surface. * * Nothing is lost: the owner still sees them on the Discovery screen, and an agent holding * real credentials discovers them the proper way — core's own authenticated * `wp-abilities/v1/abilities` listing, which returns exactly what that caller may run. * * @param bool $publish Whether to advertise gated abilities anonymously. * @param string $namespace The ability namespace. */ $publish_gated = (bool) apply_filters( 'agentimus_publish_gated_abilities', false, $namespace ); return array( 'id' => 'abilities-' . sanitize_key( $namespace ), // ⭐ THE VENDOR'S OWN NAME when they wrote one. Ability CATEGORIES are // registered with a human label — AIOSEO publishes "AIOSEO — Posts", // WooCommerce "WooCommerce", FluentBoards "FluentBoards" — and we were // printing the slug instead, which is hiding something a vendor // advertises. (An earlier note here said no honest source existed for // their capitalisation. wp_get_ability_categories() is that source; it // was simply not looked at.) // // ⚠️ Only when the group agrees on ONE labelled category. WordPress // core's two abilities sit under "Site" and "User" at once, and no // single name is true of both — that group keeps the quoted slug, which // says "this is their word, not our sentence". ⛔ ucfirst() is never the // answer: it turned real names into misspellings ("Woocommerce", "Ai"). 'title' => self::group_title( $namespace, $items ), 'type' => 'agent', // Registered either way, so the Discovery screen can still show the owner what their // site exposes — but kept out of every SERVED surface when it is all sign-in-only. 'public' => $publish_gated || $any_advertised, // ⚠️⚠️ THIS SENTENCE IS PUBLISHED. It goes into discovery.json and mcp.json, // where strangers and machines read it — and it used to end "…listed // further down, under 'For a signed-in assistant'", which is the name of a // card on OUR ADMIN SCREEN. Every site running Agentimus was telling the // open internet to look further down a page it cannot see. // ⭐ THE RULE IT BROKE: a served document is written for its reader. Admin // furniture — "below", "above", "on this screen", the name of one of our // own cards — can never appear in one, because the reader is not standing // where we are. /* translators: %d: how many jobs this plugin registered. */ 'description' => sprintf( _n( '%d job an AI assistant can run here, once it signs in.', '%d jobs an AI assistant can run here, once it signs in.', count( $items ), 'agentimus' ), count( $items ) ), 'abilities' => $abilities, 'tools' => $tools, // The resource inherits the strictest requirement of the tools inside it. Left unset it // defaulted to type "none" — telling agents the whole set was callable anonymously. // // 'basic', not 'wp': Resource::AUTH_TYPES only accepts none|apikey|basic|oauth2|oidc| // custom and silently falls back to 'none' for anything else, so 'wp' here would quietly // reinstate the very lie we are fixing. 'basic' is also the literal truth — a WordPress // application password is HTTP Basic auth over REST. 'auth' => array( 'type' => $needs_auth ? 'basic' : 'none' ), 'agent' => array( 'name' => $namespace . ' Agent', 'description' => sprintf( '%s capabilities exposed as MCP tools.', $namespace ), 'skills' => $skills, 'endpoint' => '', 'auth' => $needs_auth ? 'wp' : '', ), ); } /** * The heading for one group of jobs: the vendor's own words when they wrote * them, their slug in quotes when they didn't. * * @param string $namespace The name prefix these abilities share. * @param array $items The group's abilities. * @return string */ private static function group_title( $namespace, $items ) { $label = self::shared_category_label( $namespace, $items ); if ( '' !== $label ) { /* translators: %s: a plugin's own name for a group of jobs, e.g. "AIOSEO — Posts". */ return sprintf( __( 'Jobs from %s', 'agentimus' ), $label ); } /* translators: %s: the namespace a plugin registered its jobs under, e.g. woocommerce. */ return sprintf( __( 'Jobs from “%s”', 'agentimus' ), $namespace ); } /** * The label of the one category every ability in a group belongs to, or ''. * * ⛔ Empty is returned for every case where a single name would be a guess: no * category API, a member with no category, two categories in one group, or a * category registered without a label. We publish their name or their slug — * never a third thing we made up. * * ⚠️ THE ONE THAT GOT THROUGH. A category can be BORROWED: MailPoet files its * two abilities under WooCommerce's category, so a rule that only asked "do * they agree on one category" titled two different groups "Jobs from * WooCommerce" — one of them MailPoet's. A name is only a name if it points at * one thing. So the label is used when the category IS this group (its slug is * the namespace) or when nobody else files under it; a borrowed one names * nobody and the borrower keeps its slug. * * @param string $namespace The name prefix these abilities share. * @param array $items The group's abilities. * @return string */ private static function shared_category_label( $namespace, $items ) { if ( ! function_exists( 'wp_get_ability_categories' ) ) { return ''; } $seen = array(); foreach ( $items as $item ) { $category = self::read( isset( $item['ability'] ) ? $item['ability'] : null, 'get_category', '' ); $category = is_object( $category ) ? self::read( $category, 'get_name', '' ) : (string) $category; if ( '' === $category ) { return ''; } $seen[ $category ] = true; } if ( 1 !== count( $seen ) ) { return ''; } $wanted = key( $seen ); if ( $wanted !== $namespace && ! self::category_belongs_only_to( $wanted, $namespace ) ) { return ''; } foreach ( (array) wp_get_ability_categories() as $key => $category ) { $name = is_object( $category ) ? self::read( $category, 'get_name', (string) $key ) : (string) $key; if ( $name !== $wanted ) { continue; } $label = is_object( $category ) ? self::read( $category, 'get_label', '' ) : ( is_array( $category ) && isset( $category['label'] ) ? $category['label'] : '' ); return trim( (string) $label ); } return ''; } /** * Whether a category is used by this namespace and no other. * * ⚠️ Every REGISTERED ability counts here, including the ones we skip further * up (no REST route, filtered out). A name shared with something we don't show * is still shared, and the question being asked is whose name it is — not * what we happen to publish. * * @param string $category The category slug. * @param string $namespace The namespace claiming it. * @return bool */ private static function category_belongs_only_to( $category, $namespace ) { if ( ! function_exists( 'wp_get_abilities' ) ) { return false; // Cannot establish it is theirs alone, so do not claim it. } foreach ( (array) wp_get_abilities() as $ability ) { $name = (string) self::read( $ability, 'get_name' ); if ( '' === $name ) { continue; } $owner = strpos( $name, '/' ) ? substr( $name, 0, strpos( $name, '/' ) ) : $name; if ( $owner === $namespace ) { continue; } $theirs = self::read( $ability, 'get_category', '' ); $theirs = is_object( $theirs ) ? self::read( $theirs, 'get_name', '' ) : (string) $theirs; if ( $theirs === $category ) { return false; } } return true; } /** * What running this tool takes. Ours to say, and never louder than the truth. * * ⛔ ALWAYS a sign-in, and the reason is in the Abilities API itself: every * ability is registered WITH a permission callback. There is no such thing as * an ungated ability, so "anyone may run this" is a sentence we can never * honestly write about one. * * ⚠️ WHAT THIS REPLACED, and why it was wrong twice. The rule used to read * "advertised AND read-only ⇒ no sign-in needed". The first half of that was * corrected once already, when marking writes public published five ways to * change a shop as open to anyone. The read half survived and was just as * wrong: on a site running WooCommerce, FluentCRM, FluentBoards, AIOSEO and * WP Mail SMTP it put THIRTY-TWO tools in the public document under "no * sign-in needed" — among them woocommerce/orders-query, gated by * wc_rest_check_post_permissions(), fluent-crm/list-contacts, and * fluent-boards/list-boards, whose own description says it returns the boards * "visible to the current user". A stranger calling any of them is refused. * * ⭐ Read-only was never the question. Read-only says a tool does not WRITE; * it says nothing about whether the thing it reads is public, and someone's * customer orders are not. The vendor's `mcp.public` mark is not the question * either — that one asks us to list the tool, which we do. * * Under-claiming costs an agent one unnecessary auth header. Over-claiming * walks it into a 401 and misinforms every reader of the document. Those are * not symmetric, and the screen already says it in words: the Discovery page's * "Things Assistants Can Do" section states that every job needs a sign-in * first, including the ones that only read. * * @return string Always 'wp' — an ability is gated by its own permission callback. */ private static function auth_for() { return 'wp'; } /** * Whether the VENDOR advertises this ability — their decision, read from the * `meta.mcp.public` mark and nothing else. * * ⭐ THE RULE (his, 2026-08-15): we do not advertise what a vendor keeps back, * and we do not hide what a vendor advertises. We never invent an entry on a * plugin's behalf. So this answers one question only, and the answer belongs * to whoever registered the ability. It holds for every plugin on the site, * today's and tomorrow's — nothing here is written for a particular vendor. * * ⛔ It does NOT answer "may anyone run this". That is a separate question, * answered by what the tool does, and mixing the two published five ways to * change a shop under the words "no sign-in needed". A mark that means * "advertise me" cannot be read as "everyone may use me". * * Default false is the safe direction and the correct one: the Abilities API * requires a permission callback at registration, so an ability is gated * unless it says otherwise. Our own Registrar sets the flag FALSE deliberately, * to keep Agentimus's tools off a public surface. * * @param mixed $ability The ability object. * @return bool True when the ability declares itself advertised. */ private static function advertised( $ability ) { $meta = (array) self::read( $ability, 'get_meta', array() ); $mcp = isset( $meta['mcp'] ) && is_array( $meta['mcp'] ) ? $meta['mcp'] : array(); return ! empty( $mcp['public'] ); } /** * Read a value off an ability object via a getter, tolerating API shape drift * across Abilities API versions. * * @param mixed $ability The ability object. * @param string $method Getter name. * @param mixed $default Fallback. * @return mixed */ /** * Whether an ability is exposed as an MCP RESOURCE rather than a tool. * * The declaration is `meta.mcp.uri` ({@see \Agentimus\Abilities\Registrar::add()}'s * `$mcp` argument); the flat `meta.uri` is accepted too, since that is where the * readOnly hint already looks and an adapter version could put it either place. * * @param object $ability The ability object. * @return bool */ private static function is_resource( $ability ) { return '' !== self::resource_uri( $ability ); } /** * The MCP resource URI an ability carries, or '' when it carries none (a tool). * * @param object $ability The ability object. * @return string */ private static function resource_uri( $ability ) { $meta = (array) self::read( $ability, 'get_meta', array() ); if ( ! empty( $meta['uri'] ) ) { return (string) $meta['uri']; } return ( isset( $meta['mcp']['uri'] ) && '' !== $meta['mcp']['uri'] ) ? (string) $meta['mcp']['uri'] : ''; } private static function read( $ability, $method, $default = '' ) { if ( is_object( $ability ) && method_exists( $ability, $method ) ) { $value = $ability->$method(); return null === $value ? $default : $value; } return $default; } /** * Resolve a tool's `readOnlyHint` from the strongest available signal — a name * verb is the weakest, so it's the last resort, never the primary: * * 1. The ability's DECLARED annotation (`meta.annotations.readonly`) — the * developer's explicit contract; honoured whether true or false. The * Abilities API defaults it to null, so `isset()` reads "declared". * 2. The ability's TYPE — a resource (it carries a `uri`/`mimeType`) is a read * by definition, so it's read-only even when its name has no read verb * (e.g. a "contribution-guide" resource). * 3. A GUARDED name heuristic (see looks_read_only) — may only ever assert * true; it never overrides a declared false, and ambiguity stays false. * * @param mixed $ability The ability object. * @param string $name Ability name (e.g. "core/get-site-info"). * @return bool */ private static function read_only_hint( $ability, $name ) { $meta = (array) self::read( $ability, 'get_meta', array() ); $annotations = isset( $meta['annotations'] ) && is_array( $meta['annotations'] ) ? $meta['annotations'] : array(); // 1. An explicit declaration wins (true OR false). null/absent ⇒ undeclared. if ( isset( $annotations['readonly'] ) ) { return (bool) $annotations['readonly']; } // 2. A resource (carries a uri/mimeType) is a read, never a mutation. if ( ! empty( $meta['uri'] ) || ! empty( $meta['mimeType'] ) ) { return true; } // 3. Guarded name heuristic. return self::looks_read_only( $name ); } /** * GUARDED name heuristic for an undeclared tool: read-only only when the name * leads with a read verb AND carries no mutation token anywhere. This keeps * `get-orders` read-only while refusing to mark `get-and-delete` — a "get" that * actually writes — as safe. It only ever returns true; ambiguity stays false. * * @param string $name Ability name. * @return bool */ private static function looks_read_only( $name ) { $verb = strpos( $name, '/' ) ? substr( $name, strpos( $name, '/' ) + 1 ) : $name; // Must lead with a read verb… if ( ! preg_match( '/^(get|list|read|search|find|fetch|query|count|view)[-_]/', $verb ) ) { return false; } // …and carry no mutation token (a "get" that also writes is not "safe"). $mutations = 'create|add|update|edit|set|put|delete|remove|destroy|clear|reset|prune|purge|sync|send|cancel|refund|import|export|write|save|store|generate|issue|revoke|approve|reject'; return ! preg_match( '/[-_](' . $mutations . ')([-_]|$)/', $verb ); } }