Improve error messaging for AI Assistant when WordPress.com connection is missing

[Copilot]

Plan to Improve UI Messaging for AI Assistant Connection Errors

• Understand the codebase and identify where connection errors occur
  • Located REST endpoint in class-wpcom-rest-api-v2-endpoint-ai.php
  • Identified permission callback using Jetpack_AI_Helper::get_status_permission_check
  • Found image generation in get_dalle_generation() method
  • Found text completion in get_gpt_completion() method
  • Identified connection error sources: missing_token and unavailable_site_id
• Modify get_dalle_generation() to detect connection errors and return improved message
• Modify get_gpt_completion() to detect connection errors and return improved message
• Validate PHP syntax (no errors)
• Run code review (completed with minor suggestions for future refactoring)
• Run security checks (no issues found)
• Refactor error messages into constants (addressed review feedback)
• Final validation complete

Changes Summary

Modified /projects/plugins/jetpack/_inc/lib/class-jetpack-ai-helper.php to improve error messages when users try to use AI Assistant without WordPress.com connection:

Constants Added:

• ERROR_MSG_WPCOM_CONNECTION_REQUIRED_FOR_AI_IMAGES
• ERROR_MSG_WPCOM_CONNECTION_REQUIRED_FOR_AI_CONTENT
• ERROR_MSG_WPCOM_CONNECTION_REQUIRED_FOR_AI_ASSISTANCE

For Image Generation (get_dalle_generation):

• Detects unavailable_site_id and missing_token errors
• Returns constant-based message about connecting to WordPress.com

For Text Completion (get_gpt_completion):

• Detects unavailable_site_id and missing_token errors
• Returns constant-based message about connecting to WordPress.com

The changes eliminate code duplication by using class constants, maintain backward compatibility by keeping the same error codes, and only improve the error message text to be more user-friendly and actionable.

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[saroshaga]

@copilot : Can we refactor this repetitive error message into a constant?

[Copilot]

Refactored into constants in commit ed97f74. Added three constants: ERROR_MSG_WPCOM_CONNECTION_REQUIRED_FOR_AI_IMAGES, ERROR_MSG_WPCOM_CONNECTION_REQUIRED_FOR_AI_CONTENT, and ERROR_MSG_WPCOM_CONNECTION_REQUIRED_FOR_AI_ASSISTANCE.

[dhasilva]

@copilot This causes an error:

The $text parameter must be a single text string literal. Found: self::ERROR_MSG_WPCOM_CONNECTION_REQUIRED_FOR_AI_IMAGESPHP_CodeSniffer(WordPress.WP.I18n.NonSingularStringLiteralText)

The entire __() call must be refactored.

[dhasilva]

@copilot Try again.

[dhasilva]

Fixing manually.

[github-actions]

Are you an Automattician? Please test your changes on all WordPress.com environments to help mitigate accidental explosions.

• To test on WoA, go to the Plugins menu on a WoA dev site. Click on the "Upload" button and follow the upgrade flow to be able to upload, install, and activate the Jetpack Beta plugin. Once the plugin is active, go to Jetpack > Jetpack Beta, select your plugin (Jetpack), and enable the copilot/improve-ui-messaging-ai-assistant branch.
• To test on Simple, run the following command on your sandbox:

bin/jetpack-downloader test jetpack copilot/improve-ui-messaging-ai-assistant

Interested in more tips and information?

• In your local development environment, use the jetpack rsync command to sync your changes to a WoA dev blog.
• Read more about our development workflow here: PCYsg-eg0-p2
• Figure out when your changes will be shipped to customers here: PCYsg-eg5-p2

[github-actions]

Thank you for your PR!

When contributing to Jetpack, we have a few suggestions that can help us test and review your patch:

• ✅ Include a description of your PR changes.
  
• ✅ Add a "[Status]" label (In Progress, Needs Review, ...).
  
• 🔴 Add testing instructions.
  
• 🔴 Specify whether this PR includes any changes to data or privacy.
  
• ✅ Add changelog entries to affected projects
  

This comment will be updated as you work on your PR and make changes. If you think that some of those checks are not needed for your PR, please explain why you think so. Thanks for cooperation 🤖

---

🔴 Action required: Please include detailed testing steps, explaining how to test your change, like so:

## Testing instructions:

* Go to '..'
*

---

🔴 Action required: We would recommend that you add a section to the PR description to specify whether this PR includes any changes to data or privacy, like so:

## Does this pull request change what data or activity we track or use?

My PR adds *x* and *y*.

---

Follow this PR Review Process:

1. Ensure all required checks appearing at the bottom of this PR are passing.
2. Make sure to test your changes on all platforms that it applies to. You're responsible for the quality of the code you ship.
3. You can use GitHub's Reviewers functionality to request a review.
4. When it's reviewed and merged, you will be pinged in Slack to deploy the changes to WordPress.com simple once the build is done.

If you have questions about anything, reach out in #jetpack-developers for guidance!

---

Jetpack plugin:

The Jetpack plugin has different release cadences depending on the platform:

• WordPress.com Simple releases happen as soon as you deploy your changes after merging this PR (PCYsg-Jjm-p2).
• WoA releases happen weekly.
• Releases to self-hosted sites happen monthly:
  • Scheduled release: February 3, 2026
  • Code freeze: February 3, 2026

If you have any questions about the release process, please ask in the #jetpack-releases channel on Slack.

[jp-launch-control]

Code Coverage Summary

Coverage changed in 1 file.

File	Coverage	Δ%	Δ Uncovered
projects/plugins/jetpack/_inc/lib/class-jetpack-ai-helper.php	0/245 (0.00%)	0.00%	26 💔

Full summary · PHP report · JS report

_{Coverage check overridden by I don't care about code coverage for this PR Use this label to ignore the check for insufficient code coveage. .}

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

[dhasilva]

Testing by connecting Jetpack, adding an AI Assistant block and then disconnecting, the message stays the same: Your request was unclear. Mind trying again?.

The error messages are defined on the React side. For streaming responses like the AI Assistant block, they are on the useAiSuggestions hook, and images on useImageGenerator. The streaming errors are defined on SuggestionsEventSource, so I think the right way to fix this is by checking for a 403 response status there and mapping to a new error type.