Commit 670b037e05d for woocommerce
commit 670b037e05d43f6236a98ddffae81d8741bcf80c
Author: AnnaMag <AnnaMag@users.noreply.github.com>
Date: Thu Nov 19 13:18:19 2026 +0100
Agent readiness: list whether llms.txt holds WooCommerce's store guidance (#70909)
* Agent readiness: list whether llms.txt holds WooCommerce's store guidance
With WooCommerce's llms.txt fallback (#70741), the declared-to-agents block
lists whether the served llms.txt, from WooCommerce or another provider, holds
WooCommerce's guidance (Store API, UCP, policies). Information only; not listed
without the fallback.
* Agent readiness: mark the llms.txt guidance changelog as dev-only
diff --git a/plugins/woocommerce/changelog/add-agent-readiness-llms-txt-guidance b/plugins/woocommerce/changelog/add-agent-readiness-llms-txt-guidance
new file mode 100644
index 00000000000..ee8f2f70b65
--- /dev/null
+++ b/plugins/woocommerce/changelog/add-agent-readiness-llms-txt-guidance
@@ -0,0 +1,3 @@
+Significance: patch
+Type: dev
+Comment: Agent readiness: list whether the served llms.txt holds WooCommerce's store guidance; nothing ships to merchants.
diff --git a/plugins/woocommerce/changelog/fix-agent-readiness-llms-guidance-checks b/plugins/woocommerce/changelog/fix-agent-readiness-llms-guidance-checks
new file mode 100644
index 00000000000..b7164768df7
--- /dev/null
+++ b/plugins/woocommerce/changelog/fix-agent-readiness-llms-guidance-checks
@@ -0,0 +1,4 @@
+Significance: patch
+Type: fix
+
+Treat a rate-limited or truncated llms.txt read as couldn't check, not missing.
diff --git a/plugins/woocommerce/src/Internal/AgentReadiness/DeclaredToAgents.php b/plugins/woocommerce/src/Internal/AgentReadiness/DeclaredToAgents.php
index 96289703f62..45c32145e66 100644
--- a/plugins/woocommerce/src/Internal/AgentReadiness/DeclaredToAgents.php
+++ b/plugins/woocommerce/src/Internal/AgentReadiness/DeclaredToAgents.php
@@ -60,9 +60,47 @@ class DeclaredToAgents {
'found' => $line[1],
);
}
+ $status = $this->llms_txt_status();
+ // In a subdirectory WooCommerce serves llms.txt under the home path, not at the host root read here.
+ if ( null !== $status && '' !== trim( $status['section'] ) && '' === trim( (string) wp_parse_url( home_url(), PHP_URL_PATH ), '/' ) ) {
+ $items[] = array(
+ 'id' => 'llms-txt-woocommerce-guidance',
+ 'name' => __( 'WooCommerce’s store guidance in llms.txt (Store API, UCP, policies)', 'woocommerce' ),
+ 'found' => self::has_guidance( $responses, $status['section'] ),
+ );
+ }
return $items;
}
+ /**
+ * WooCommerce's llms.txt status, null without its llms.txt fallback (woocommerce #70741).
+ *
+ * @return array{status:string,section:string}|null
+ */
+ protected function llms_txt_status(): ?array {
+ return StoreOutputChecks::core_llms_txt_status();
+ }
+
+ /**
+ * Whether the served llms.txt, from WooCommerce or any other provider, holds WooCommerce's guidance.
+ * Null when the file couldn't be checked (refused, rate-limited, or truncated before a match).
+ *
+ * @param StoreResponses $responses Responses of the scan.
+ * @param string $section Guidance WooCommerce adds.
+ */
+ private static function has_guidance( StoreResponses $responses, string $section ): ?bool {
+ $served = self::file_served( $responses, '/llms.txt' );
+ if ( true !== $served ) {
+ return $served;
+ }
+ $response = $responses->get( StoreOutputChecks::host_root( '/llms.txt' ) );
+ $body = (string) ( $response['body'] ?? '' );
+ if ( StoreOutputChecks::has_llms_txt_guidance( $body, $section ) ) {
+ return true;
+ }
+ return ! empty( $response['truncated'] ) ? null : false;
+ }
+
/**
* Items served as a file at a known path, by id.
*
@@ -278,6 +316,7 @@ class DeclaredToAgents {
/**
* Whether a path answers with a text file. A theme that answers every URL with a page, or a host
* that answers unknown paths with a 200 JSON or HTML error, has no such file.
+ * Null when a 200 body was cut off before any content, so a blank prefix is not a missing file.
*
* @param StoreResponses $responses Store responses.
* @param string $path Path from the host root.
@@ -288,6 +327,10 @@ class DeclaredToAgents {
return null;
}
$body = ltrim( $response['body'], " \t\r\n\xEF\xBB\xBF" );
+ // Only a 200 can be a file that was cut off before content; a truncated 404 stays missing.
+ if ( 200 === $response['status'] && '' === $body && ! empty( $response['truncated'] ) ) {
+ return null;
+ }
return 200 === $response['status'] && '' !== $body && '<' !== $body[0]
&& 0 !== stripos( $response['headers']['content-type'] ?? '', 'text/html' )
&& null === json_decode( $body );
diff --git a/plugins/woocommerce/src/Internal/AgentReadiness/ReadinessCheckPage.php b/plugins/woocommerce/src/Internal/AgentReadiness/ReadinessCheckPage.php
index be9c10435ee..8dbe73ec8a8 100644
--- a/plugins/woocommerce/src/Internal/AgentReadiness/ReadinessCheckPage.php
+++ b/plugins/woocommerce/src/Internal/AgentReadiness/ReadinessCheckPage.php
@@ -898,15 +898,24 @@ class ReadinessCheckPage implements RegisterHooksInterface {
return null;
}
$found = array_filter( $items, static fn( array $item ): bool => true === ( $item['found'] ?? null ) );
+ $text = sprintf(
+ /* translators: %s: how many items were found, such as "Found 4 of 33". */
+ __( 'Optional files that some AI assistants look for. You don’t need to fix anything. %s.', 'woocommerce' ),
+ /* translators: 1: number of items found, 2: number of items looked for. */
+ sprintf( __( 'Found %1$s of %2$s', 'woocommerce' ), number_format_i18n( count( $found ) ), number_format_i18n( count( $items ) ) )
+ );
+ // Served llms.txt caches guidance for a few minutes for anonymous requests, so a fresh
+ // policy/MCP/UCP change can briefly look missing until that cache expires.
+ foreach ( $items as $item ) {
+ if ( 'llms-txt-woocommerce-guidance' === ( $item['id'] ?? '' ) && false === ( $item['found'] ?? null ) ) {
+ $text .= ' ' . __( 'If you just changed policy pages, MCP, or UCP, wait a few minutes and check again. WooCommerce caches its llms.txt briefly.', 'woocommerce' );
+ break;
+ }
+ }
return array(
'title' => __( 'What does your store share with AI assistants?', 'woocommerce' ),
'badge' => self::badge_data( array( 'off', __( 'Optional', 'woocommerce' ) ) ),
- 'text' => sprintf(
- /* translators: %s: how many items were found, such as "Found 4 of 33". */
- __( 'Optional files that some AI assistants look for. You don’t need to fix anything. %s.', 'woocommerce' ),
- /* translators: 1: number of items found, 2: number of items looked for. */
- sprintf( __( 'Found %1$s of %2$s', 'woocommerce' ), number_format_i18n( count( $found ) ), number_format_i18n( count( $items ) ) )
- ),
+ 'text' => $text,
'items' => array_map(
static fn( array $item ): array => array(
'name' => (string) ( $item['name'] ?? '' ),
diff --git a/plugins/woocommerce/src/Internal/AgentReadiness/StoreOutputChecks.php b/plugins/woocommerce/src/Internal/AgentReadiness/StoreOutputChecks.php
index dbe29d2bdf3..b48b46c0955 100644
--- a/plugins/woocommerce/src/Internal/AgentReadiness/StoreOutputChecks.php
+++ b/plugins/woocommerce/src/Internal/AgentReadiness/StoreOutputChecks.php
@@ -5,6 +5,7 @@ namespace Automattic\WooCommerce\Internal\AgentReadiness;
use Automattic\WooCommerce\Enums\ProductStatus;
use Automattic\WooCommerce\Internal\ComingSoon\ComingSoonHelper;
+use Automattic\WooCommerce\Internal\LlmsTxt\LlmsTxt;
use Automattic\WooCommerce\StoreApi\Utilities\Ucp\Utils as UcpUtils;
defined( 'ABSPATH' ) || exit;
@@ -893,6 +894,35 @@ class StoreOutputChecks {
return (bool) $test( $body );
}
+ /**
+ * Whether a served llms.txt holds WooCommerce's guidance, as WooCommerce's own file does.
+ * Line endings are normalized so a CRLF copy of the section still matches.
+ *
+ * @param string $body Served llms.txt.
+ * @param string $section Guidance WooCommerce adds, '' when it adds none.
+ */
+ public static function has_llms_txt_guidance( string $body, string $section ): bool {
+ $section = trim( str_replace( "\r\n", "\n", $section ) );
+ $body = str_replace( "\r\n", "\n", $body );
+ return '' !== $section && str_contains( $body, $section );
+ }
+
+ /**
+ * WooCommerce's llms.txt status: disabled, physical_file or unknown, with the guidance it adds.
+ * Null when reading status fails.
+ *
+ * @return array{status:string,section:string}|null
+ */
+ public static function core_llms_txt_status(): ?array {
+ try {
+ $status = wc_get_container()->get( LlmsTxt::class )->get_status();
+ } catch ( \Throwable $e ) {
+ wc_get_logger()->warning( 'Agent readiness could not read the llms.txt status: ' . $e->getMessage(), array( 'source' => 'agent-readiness' ) );
+ return null;
+ }
+ return is_string( $status['status'] ?? null ) && is_string( $status['section'] ?? null ) ? $status : null;
+ }
+
/**
* Whether the first few links in llms.txt to the store's own pages open. Links to other sites
* aren't loaded. Null when one couldn't be loaded and none was broken.
@@ -930,15 +960,15 @@ class StoreOutputChecks {
/**
* Whether a status says the store's request to itself was refused or failed, not that the
- * page is missing: a server error, or a firewall or security plugin answering 401 or 403.
- * A check then reports couldn't check, as it does when the page times out.
+ * page is missing: a server error, rate limit (429), or a firewall or security plugin
+ * answering 401 or 403. A check then reports couldn't check, as it does when the page times out.
*
* @since 11.4.0
*
* @param int $status HTTP status.
*/
public static function blocked( int $status ): bool {
- return $status >= 500 || in_array( $status, array( 401, 403 ), true );
+ return $status >= 500 || in_array( $status, array( 401, 403, 429 ), true );
}
/**
diff --git a/plugins/woocommerce/tests/php/src/Internal/AgentReadiness/AgenticCommerceSettingsTest.php b/plugins/woocommerce/tests/php/src/Internal/AgentReadiness/AgenticCommerceSettingsTest.php
index 1a9bf40158e..317e55bdf1b 100644
--- a/plugins/woocommerce/tests/php/src/Internal/AgentReadiness/AgenticCommerceSettingsTest.php
+++ b/plugins/woocommerce/tests/php/src/Internal/AgentReadiness/AgenticCommerceSettingsTest.php
@@ -634,6 +634,21 @@ class AgenticCommerceSettingsTest extends WC_Unit_Test_Case {
$view['declared']['items'],
'Every item, found or not'
);
+
+ $report = get_option( 'woocommerce_agent_readiness_report' );
+ $report['declared'] = array(
+ array(
+ 'id' => 'llms-txt-woocommerce-guidance',
+ 'name' => 'WooCommerce store guidance',
+ 'found' => false,
+ ),
+ );
+ update_option( 'woocommerce_agent_readiness_report', $report );
+ $this->assertStringContainsString(
+ 'WooCommerce caches its llms.txt briefly',
+ $this->view()['declared']['text'],
+ 'Missing WooCommerce guidance notes the short llms.txt cache'
+ );
$this->assertSame(
array(
'intent' => 'none',
diff --git a/plugins/woocommerce/tests/php/src/Internal/AgentReadiness/DeclaredToAgentsTest.php b/plugins/woocommerce/tests/php/src/Internal/AgentReadiness/DeclaredToAgentsTest.php
index 675b0f5c96b..9da89e1cf77 100644
--- a/plugins/woocommerce/tests/php/src/Internal/AgentReadiness/DeclaredToAgentsTest.php
+++ b/plugins/woocommerce/tests/php/src/Internal/AgentReadiness/DeclaredToAgentsTest.php
@@ -63,19 +63,21 @@ class DeclaredToAgentsTest extends WC_Unit_Test_Case {
}
/**
- * @testdox A 401 or 403 is not checked: a firewall can refuse a file that exists.
+ * @testdox A 401, 403 or 429 is not checked: a firewall or rate limit can refuse a file that exists.
*/
public function test_blocked_response_is_not_checked(): void {
$results = $this->results(
array(
'/ai.txt' => array( 403, 'Forbidden' ),
'/.well-known/agent-card.json' => array( 401, '' ),
+ '/llms-full.txt' => array( 429, 'Too Many Requests' ),
'markdown /' => array( 403, '' ),
)
);
$this->assertNull( $results['ai-txt'] );
$this->assertNull( $results['a2a-agent-card'] );
+ $this->assertNull( $results['llms-full'] );
$this->assertNull( $results['markdown-pages'] );
}
@@ -85,17 +87,25 @@ class DeclaredToAgentsTest extends WC_Unit_Test_Case {
public function test_files(): void {
$results = $this->results(
array(
- '/ai.txt' => array( 200, 'User-Agent: *' ),
- '/.well-known/agents.json' => array( 200, '<!doctype html><html></html>' ),
- '/AGENTS.md' => array( 200, '{"code":"not_found","message":"No route"}' ),
- '/auth.md' => array( 200, 'Not found', array( 'content-type' => 'text/html; charset=UTF-8' ) ),
- '/sitemap.md' => array( 200, "\xEF\xBB\xBF<!doctype html><html></html>" ),
+ '/ai.txt' => array( 200, 'User-Agent: *' ),
+ '/.well-known/agents.json' => array( 200, '<!doctype html><html></html>' ),
+ '/AGENTS.md' => array( 200, '{"code":"not_found","message":"No route"}' ),
+ '/auth.md' => array( 200, 'Not found', array( 'content-type' => 'text/html; charset=UTF-8' ) ),
+ '/sitemap.md' => array( 200, "\xEF\xBB\xBF<!doctype html><html></html>" ),
+ '/.well-known/security.txt' => array(
+ 404,
+ "\n\n",
+ array(
+ 'content-type' => 'text/plain',
+ 'content-length' => '999999',
+ ),
+ ),
)
);
$this->assertTrue( $results['ai-txt'] );
$this->assertFalse( $results['agents-json'], 'A page is not a JSON document' );
- $this->assertFalse( $results['security-txt'], 'A 404' );
+ $this->assertFalse( $results['security-txt'], 'A truncated 404 is still missing' );
$this->assertFalse( $results['agents-md'], 'A 200 JSON error is not a file' );
$this->assertFalse( $results['auth-md'], 'A 200 HTML answer is not a file' );
$this->assertFalse( $results['sitemap-md'], 'A page behind a byte order mark is not a file' );
@@ -488,4 +498,79 @@ class DeclaredToAgentsTest extends WC_Unit_Test_Case {
$this->assertNull( $item['found'], $item['id'] );
}
}
+
+ /**
+ * @testdox With WooCommerce's llms.txt fallback, its guidance is found when the served llms.txt holds it, from any provider; without the fallback the item isn't listed.
+ */
+ public function test_llms_txt_guidance(): void {
+ $section = "## Agentic capabilities\n\n- [WooCommerce Store API](" . home_url( '/wp-json/wc/store/v1' ) . ')';
+ $sut = new class() extends DeclaredToAgents {
+ /**
+ * The status to report.
+ *
+ * @var array{status:string,section:string}|null
+ */
+ public $status;
+
+ /**
+ * The status set by the test.
+ */
+ protected function llms_txt_status(): ?array {
+ return $this->status;
+ }
+ };
+ $found = function ( array $responses ) use ( $sut ): array {
+ $this->results( $responses );
+ return array_column( $sut->all( wc_get_container()->get( StoreOutputChecks::class )->responses() ), 'found', 'id' );
+ };
+
+ $this->assertArrayNotHasKey( 'llms-txt-woocommerce-guidance', $found( array() ), 'Not listed without the fallback' );
+
+ $sut->status = array(
+ 'status' => 'unknown',
+ 'section' => $section . "\n",
+ );
+ $this->assertTrue( $found( array( '/llms.txt' => array( 200, "# Shop\n\n" . $section . "\n" ) ) )['llms-txt-woocommerce-guidance'] );
+ $this->assertTrue(
+ $found(
+ array(
+ '/llms.txt' => array( 200, "# Shop\r\n\r\n" . str_replace( "\n", "\r\n", $section ) . "\r\n" ),
+ )
+ )['llms-txt-woocommerce-guidance'],
+ 'CRLF line endings still match'
+ );
+ $this->assertFalse( $found( array( '/llms.txt' => array( 200, "# Shop\n\n- [About](" . home_url( '/about/' ) . ')' ) ) )['llms-txt-woocommerce-guidance'], 'Another provider\'s file without it' );
+ $this->assertFalse( $found( array() )['llms-txt-woocommerce-guidance'], 'No llms.txt' );
+ $this->assertNull( $found( array( '/llms.txt' => array( 503, '' ) ) )['llms-txt-woocommerce-guidance'], 'Couldn\'t check' );
+ $this->assertNull( $found( array( '/llms.txt' => array( 429, '' ) ) )['llms-txt-woocommerce-guidance'], 'Rate limited' );
+ $this->assertNull(
+ $found(
+ array(
+ '/llms.txt' => array( 200, "# Shop\n", array( 'content-length' => '999999' ) ),
+ )
+ )['llms-txt-woocommerce-guidance'],
+ 'Truncated body with no match is couldn\'t check'
+ );
+ $this->assertNull(
+ $found(
+ array(
+ '/llms.txt' => array(
+ 200,
+ "\n\n",
+ array(
+ 'content-type' => 'text/plain',
+ 'content-length' => '999999',
+ ),
+ ),
+ )
+ )['llms-txt-woocommerce-guidance'],
+ 'A body cut off in leading blank lines is couldn\'t check'
+ );
+
+ $sut->status = array(
+ 'status' => 'disabled',
+ 'section' => '',
+ );
+ $this->assertArrayNotHasKey( 'llms-txt-woocommerce-guidance', $found( array() ), 'Not listed while WooCommerce adds no guidance' );
+ }
}