feat(web): surface actionable run-failure guidance for common errors (#5308)

The daemon already classifies run failures into failure_category / user_action
(run-failure-classification.ts), but the chat error card only mapped ~7 codes to
clear copy — everything else fell back to the generic "Task failed" title plus
the raw upstream string, so users hitting common failures could not tell the
cause or the fix (#895).

Extend resolveRunFailureUi to name the failure type and give a one-line fix for
eight more high-frequency, clear-root-cause codes, with the raw error preserved
in the card's collapsible source area:

- AGENT_UNAVAILABLE (CLI not installed)
- AGENT_PROMPT_TOO_LARGE (shorten input / new conversation)
- AMR_MODEL_UNAVAILABLE (switch model)
- TOOL_LOOP_DETECTED (check target, then retry)
- ROLE_MARKER_HALLUCINATION (retry recovers)
- AGENT_RUNTIME_DEF_INVALID (update / contact support)
- RATE_LIMITED (non-antigravity: wait/switch, keeps AMR promotion)
- UPSTREAM_UNAVAILABLE (transient, keeps AMR promotion)

The six agent-agnostic codes resolve before the amr/antigravity branches so a
hosted run also gets the specific guidance. Adds 7 title keys + 8 message keys
across all 18 locales and updates amr-guidance unit tests.

Co-authored-by: xiaoche-hub <298951296+xiaoche-hub@users.noreply.github.com>
Co-authored-by: Cursor <cursoragent@cursor.com>

Author: 3 people

apps/web/src/i18n/locales/ar.ts

@@ -44,6 +44,21 @@ export const ar: Dict = {
   'chat.runError.sourceLabel': 'مصدر الخطأ',
   'chat.runError.sourceExpandAria': 'توسيع مصدر الخطأ',
   'chat.runError.sourceCollapseAria': 'طي مصدر الخطأ',
+  'chat.runError.title.cliMissing': 'الوكيل غير مثبَّت',
+  'chat.runError.title.promptTooLarge': 'الإدخال طويل جدًا',
+  'chat.runError.title.modelUnavailable': 'النموذج غير متاح',
+  'chat.runError.title.upstreamUnavailable': 'الخدمة غير متاحة مؤقتًا',
+  'chat.runError.title.toolLoop': 'عالق في حلقة',
+  'chat.runError.title.outputInvalid': 'مخرجات النموذج غير صالحة',
+  'chat.runError.title.runtimeConfig': 'خطأ في الإعداد',
+  'chat.runError.cliMissingMessage': 'لم يتم العثور على أداة سطر الأوامر لـ {agent}. ثبّتها وتأكد من وجودها في PATH ثم أعد المحاولة.',
+  'chat.runError.promptTooLargeMessage': 'تجاوزت هذه الجولة حد سياق النموذج. اختصر الطلب أو أزل المرفقات أو ابدأ محادثة جديدة ثم أعد المحاولة.',
+  'chat.runError.modelUnavailableMessage': 'النموذج المحدد غير متاح أو غير موجود. بدّل إلى نموذج آخر في الإعدادات ثم أعد المحاولة.',
+  'chat.runError.rateLimitedMessage': 'لقد بلغت حد استخدام خدمة النموذج. انتظر قليلاً ثم أعد المحاولة، أو بدّل إلى نموذج أو خدمة أخرى.',
+  'chat.runError.upstreamUnavailableMessage': 'خدمة النموذج غير متاحة مؤقتًا — عادةً بسبب عدم استقرار المصدر أو مشكلة في الشبكة/الوكيل. أعد المحاولة بعد قليل.',
+  'chat.runError.toolLoopMessage': 'كرّر {agent} الإجراء نفسه دون تقدّم فتوقّف. تحقق من الملف أو الأمر المستهدف ثم أعد المحاولة.',
+  'chat.runError.outputInvalidMessage': 'أنتج النموذج مخرجات غير صالحة وتم إيقاف هذه الجولة. عادةً ما تحل إعادة المحاولة المشكلة.',
+  'chat.runError.runtimeConfigMessage': 'إعداد وقت التشغيل للوكيل المحدد غير صالح، لذلك تعذّر بدء التشغيل. حدِّث إلى أحدث إصدار أو تواصل مع الدعم.',
   'common.cancel': 'إلغاء',
   'chat.selectFromLibrary': 'استيراد من المكتبة',
   'chat.importFigma': 'استيراد من Figma',

apps/web/src/i18n/locales/de.ts

@@ -44,6 +44,21 @@ export const de: Dict = {
   'chat.runError.sourceLabel': 'Fehlerquelle',
   'chat.runError.sourceExpandAria': 'Fehlerquelle einblenden',
   'chat.runError.sourceCollapseAria': 'Fehlerquelle ausblenden',
+  'chat.runError.title.cliMissing': 'Agent nicht installiert',
+  'chat.runError.title.promptTooLarge': 'Eingabe zu lang',
+  'chat.runError.title.modelUnavailable': 'Modell nicht verfügbar',
+  'chat.runError.title.upstreamUnavailable': 'Dienst vorübergehend nicht verfügbar',
+  'chat.runError.title.toolLoop': 'In einer Schleife stecken',
+  'chat.runError.title.outputInvalid': 'Ungültige Modellausgabe',
+  'chat.runError.title.runtimeConfig': 'Konfigurationsfehler',
+  'chat.runError.cliMissingMessage': 'Das Kommandozeilen-Tool von {agent} wurde nicht gefunden. Installiere es und stelle sicher, dass es im PATH liegt, und versuche es dann erneut.',
+  'chat.runError.promptTooLargeMessage': 'Diese Runde hat das Kontextlimit des Modells überschritten. Kürze deine Eingabe, entferne Anhänge oder starte eine neue Unterhaltung und versuche es erneut.',
+  'chat.runError.modelUnavailableMessage': 'Das ausgewählte Modell ist nicht verfügbar oder existiert nicht. Wechsle in den Einstellungen zu einem anderen Modell und versuche es erneut.',
+  'chat.runError.rateLimitedMessage': 'Das Nutzungslimit des Modelldienstes wurde erreicht. Warte einen Moment und versuche es erneut oder wechsle zu einem anderen Modell oder Dienst.',
+  'chat.runError.upstreamUnavailableMessage': 'Der Modelldienst ist vorübergehend nicht verfügbar – meist wegen Upstream-Störungen oder eines Netzwerk-/Proxy-Problems. Versuche es gleich erneut.',
+  'chat.runError.toolLoopMessage': '{agent} hat dieselbe Aktion ohne Fortschritt wiederholt und wurde gestoppt. Prüfe die Zieldatei oder den Befehl und versuche es erneut.',
+  'chat.runError.outputInvalidMessage': 'Das Modell hat ungültige Ausgabe erzeugt und diese Runde wurde abgebrochen. Ein erneuter Versuch behebt das meist.',
+  'chat.runError.runtimeConfigMessage': 'Die Laufzeitkonfiguration des ausgewählten Agents ist ungültig, daher konnte der Lauf nicht starten. Aktualisiere auf die neueste Version oder kontaktiere den Support.',
   'common.cancel': 'Abbrechen',
   'chat.selectFromLibrary': 'Aus Bibliothek importieren',
   'chat.importFigma': 'Aus Figma importieren',

apps/web/src/i18n/locales/en.ts

@@ -44,6 +44,21 @@ export const en: Dict = {
   'chat.runError.sourceLabel': 'Error source',
   'chat.runError.sourceExpandAria': 'Expand error source',
   'chat.runError.sourceCollapseAria': 'Collapse error source',
+  'chat.runError.title.cliMissing': 'Agent not installed',
+  'chat.runError.title.promptTooLarge': 'Input too long',
+  'chat.runError.title.modelUnavailable': 'Model unavailable',
+  'chat.runError.title.upstreamUnavailable': 'Service temporarily unavailable',
+  'chat.runError.title.toolLoop': 'Stuck in a loop',
+  'chat.runError.title.outputInvalid': 'Invalid model output',
+  'chat.runError.title.runtimeConfig': 'Configuration error',
+  'chat.runError.cliMissingMessage': 'The {agent} command-line tool wasn\'t found. Install it and make sure it\'s on your PATH, then retry.',
+  'chat.runError.promptTooLargeMessage': 'This turn exceeded the model\'s context limit. Shorten your prompt, remove attachments, or start a new conversation, then retry.',
+  'chat.runError.modelUnavailableMessage': 'The selected model is unavailable or does not exist. Switch to another model in Settings, then retry.',
+  'chat.runError.rateLimitedMessage': 'You\'ve hit the model service\'s usage limit. Wait a moment and retry, or switch to another model or service.',
+  'chat.runError.upstreamUnavailableMessage': 'The model service is temporarily unavailable — usually upstream instability or a network/proxy issue. Retry in a moment.',
+  'chat.runError.toolLoopMessage': '{agent} kept repeating the same action without progress and was stopped. Check the target file or command, then retry.',
+  'chat.runError.outputInvalidMessage': 'The model produced invalid output and this turn was interrupted. Retrying usually recovers.',
+  'chat.runError.runtimeConfigMessage': 'The selected agent\'s runtime configuration is invalid, so the run could not start. Update to the latest version or contact support.',
   'common.cancel': 'Cancel',
   'chat.selectFromLibrary': 'Import from library',
   'chat.importFigma': 'Import from Figma',

apps/web/src/i18n/locales/es-ES.ts

@@ -44,6 +44,21 @@ export const esES: Dict = {
   'chat.runError.sourceLabel': 'Origen del error',
   'chat.runError.sourceExpandAria': 'Mostrar el origen del error',
   'chat.runError.sourceCollapseAria': 'Ocultar el origen del error',
+  'chat.runError.title.cliMissing': 'Agente no instalado',
+  'chat.runError.title.promptTooLarge': 'Entrada demasiado larga',
+  'chat.runError.title.modelUnavailable': 'Modelo no disponible',
+  'chat.runError.title.upstreamUnavailable': 'Servicio temporalmente no disponible',
+  'chat.runError.title.toolLoop': 'Atascado en un bucle',
+  'chat.runError.title.outputInvalid': 'Salida del modelo no válida',
+  'chat.runError.title.runtimeConfig': 'Error de configuración',
+  'chat.runError.cliMissingMessage': 'No se encontró la herramienta de línea de comandos de {agent}. Instálala y asegúrate de que esté en el PATH, luego reinténtalo.',
+  'chat.runError.promptTooLargeMessage': 'Este turno superó el límite de contexto del modelo. Acorta tu mensaje, quita adjuntos o inicia una nueva conversación y reinténtalo.',
+  'chat.runError.modelUnavailableMessage': 'El modelo seleccionado no está disponible o no existe. Cambia a otro modelo en Ajustes y reinténtalo.',
+  'chat.runError.rateLimitedMessage': 'Has alcanzado el límite de uso del servicio del modelo. Espera un momento y reinténtalo, o cambia a otro modelo o servicio.',
+  'chat.runError.upstreamUnavailableMessage': 'El servicio del modelo no está disponible temporalmente, normalmente por inestabilidad del proveedor o un problema de red/proxy. Reinténtalo en un momento.',
+  'chat.runError.toolLoopMessage': '{agent} repitió la misma acción sin avanzar y se detuvo. Revisa el archivo o el comando de destino y reinténtalo.',
+  'chat.runError.outputInvalidMessage': 'El modelo produjo una salida no válida y este turno se interrumpió. Reintentar suele resolverlo.',
+  'chat.runError.runtimeConfigMessage': 'La configuración de ejecución del agente seleccionado no es válida, por lo que no se pudo iniciar. Actualiza a la última versión o contacta con soporte.',
   'common.cancel': 'Cancelar',
   'chat.selectFromLibrary': 'Importar de la biblioteca',
   'chat.importFigma': 'Importar de Figma',

apps/web/src/i18n/locales/fa.ts

@@ -44,6 +44,21 @@ export const fa: Dict = {
   'chat.runError.sourceLabel': 'منبع خطا',
   'chat.runError.sourceExpandAria': 'گسترش منبع خطا',
   'chat.runError.sourceCollapseAria': 'جمع‌کردن منبع خطا',
+  'chat.runError.title.cliMissing': 'عامل نصب نشده است',
+  'chat.runError.title.promptTooLarge': 'ورودی بیش از حد طولانی است',
+  'chat.runError.title.modelUnavailable': 'مدل در دسترس نیست',
+  'chat.runError.title.upstreamUnavailable': 'سرویس موقتاً در دسترس نیست',
+  'chat.runError.title.toolLoop': 'گیرکرده در حلقه',
+  'chat.runError.title.outputInvalid': 'خروجی نامعتبر مدل',
+  'chat.runError.title.runtimeConfig': 'خطای پیکربندی',
+  'chat.runError.cliMissingMessage': 'ابزار خط فرمان {agent} پیدا نشد. آن را نصب کنید و مطمئن شوید در PATH قرار دارد، سپس دوباره تلاش کنید.',
+  'chat.runError.promptTooLargeMessage': 'این نوبت از محدودیت زمینه مدل فراتر رفت. پرامپت را کوتاه کنید، پیوست‌ها را کم کنید یا گفت‌وگوی جدیدی شروع کنید و دوباره تلاش کنید.',
+  'chat.runError.modelUnavailableMessage': 'مدل انتخاب‌شده در دسترس نیست یا وجود ندارد. در تنظیمات به مدل دیگری تغییر دهید و دوباره تلاش کنید.',
+  'chat.runError.rateLimitedMessage': 'به محدودیت استفاده از سرویس مدل رسیده‌اید. کمی صبر کنید و دوباره تلاش کنید، یا به مدل یا سرویس دیگری تغییر دهید.',
+  'chat.runError.upstreamUnavailableMessage': 'سرویس مدل موقتاً در دسترس نیست — معمولاً به دلیل بی‌ثباتی سرویس بالادستی یا مشکل شبکه/پروکسی. کمی بعد دوباره تلاش کنید.',
+  'chat.runError.toolLoopMessage': '{agent} همان عمل را بدون پیشرفت تکرار کرد و متوقف شد. فایل یا فرمان هدف را بررسی کنید و دوباره تلاش کنید.',
+  'chat.runError.outputInvalidMessage': 'مدل خروجی نامعتبری تولید کرد و این نوبت قطع شد. معمولاً تلاش دوباره مشکل را حل می‌کند.',
+  'chat.runError.runtimeConfigMessage': 'پیکربندی زمان‌اجرای عامل انتخاب‌شده نامعتبر است، بنابراین اجرا آغاز نشد. به آخرین نسخه به‌روزرسانی کنید یا با پشتیبانی تماس بگیرید.',
   'common.cancel': 'لغو',
   'chat.selectFromLibrary': 'وارد کردن از کتابخانه',
   'chat.importFigma': 'وارد کردن از Figma',

apps/web/src/i18n/locales/fr.ts

@@ -44,6 +44,21 @@ export const fr: Dict = {
   'chat.runError.sourceLabel': 'Source de l’erreur',
   'chat.runError.sourceExpandAria': 'Afficher la source de l’erreur',
   'chat.runError.sourceCollapseAria': 'Masquer la source de l’erreur',
+  'chat.runError.title.cliMissing': 'Agent non installé',
+  'chat.runError.title.promptTooLarge': 'Entrée trop longue',
+  'chat.runError.title.modelUnavailable': 'Modèle indisponible',
+  'chat.runError.title.upstreamUnavailable': 'Service temporairement indisponible',
+  'chat.runError.title.toolLoop': 'Bloqué dans une boucle',
+  'chat.runError.title.outputInvalid': 'Sortie du modèle invalide',
+  'chat.runError.title.runtimeConfig': 'Erreur de configuration',
+  'chat.runError.cliMissingMessage': 'L’outil en ligne de commande de {agent} est introuvable. Installez-le et assurez-vous qu’il figure dans le PATH, puis réessayez.',
+  'chat.runError.promptTooLargeMessage': 'Ce tour a dépassé la limite de contexte du modèle. Raccourcissez votre message, retirez des pièces jointes ou démarrez une nouvelle conversation, puis réessayez.',
+  'chat.runError.modelUnavailableMessage': 'Le modèle sélectionné est indisponible ou inexistant. Passez à un autre modèle dans les Paramètres, puis réessayez.',
+  'chat.runError.rateLimitedMessage': 'Vous avez atteint la limite d’utilisation du service de modèle. Patientez un instant et réessayez, ou changez de modèle ou de service.',
+  'chat.runError.upstreamUnavailableMessage': 'Le service de modèle est temporairement indisponible, généralement en raison d’une instabilité en amont ou d’un problème réseau/proxy. Réessayez dans un instant.',
+  'chat.runError.toolLoopMessage': '{agent} a répété la même action sans progresser et a été arrêté. Vérifiez le fichier ou la commande cible, puis réessayez.',
+  'chat.runError.outputInvalidMessage': 'Le modèle a produit une sortie invalide et ce tour a été interrompu. Réessayer suffit généralement.',
+  'chat.runError.runtimeConfigMessage': 'La configuration d’exécution de l’agent sélectionné est invalide, l’exécution n’a donc pas pu démarrer. Mettez à jour vers la dernière version ou contactez le support.',
   'common.cancel': 'Annuler',
   'chat.selectFromLibrary': 'Importer depuis la bibliothèque',
   'chat.importFigma': 'Importer depuis Figma',

apps/web/src/i18n/locales/hu.ts

@@ -44,6 +44,21 @@ export const hu: Dict = {
   'chat.runError.sourceLabel': 'Hibaforrás',
   'chat.runError.sourceExpandAria': 'Hibaforrás kibontása',
   'chat.runError.sourceCollapseAria': 'Hibaforrás összecsukása',
+  'chat.runError.title.cliMissing': 'Az ügynök nincs telepítve',
+  'chat.runError.title.promptTooLarge': 'Túl hosszú bemenet',
+  'chat.runError.title.modelUnavailable': 'A modell nem érhető el',
+  'chat.runError.title.upstreamUnavailable': 'A szolgáltatás átmenetileg nem érhető el',
+  'chat.runError.title.toolLoop': 'Végtelen ciklusban ragadt',
+  'chat.runError.title.outputInvalid': 'Érvénytelen modellkimenet',
+  'chat.runError.title.runtimeConfig': 'Konfigurációs hiba',
+  'chat.runError.cliMissingMessage': 'A(z) {agent} parancssori eszköze nem található. Telepítsd, és győződj meg róla, hogy szerepel a PATH-ban, majd próbáld újra.',
+  'chat.runError.promptTooLargeMessage': 'Ez a kör túllépte a modell kontextushatárát. Rövidítsd le a promptot, távolíts el mellékleteket, vagy indíts új beszélgetést, majd próbáld újra.',
+  'chat.runError.modelUnavailableMessage': 'A kiválasztott modell nem érhető el vagy nem létezik. Válts át másik modellre a Beállításokban, majd próbáld újra.',
+  'chat.runError.rateLimitedMessage': 'Elérted a modellszolgáltatás használati korlátját. Várj egy kicsit, és próbáld újra, vagy válts másik modellre vagy szolgáltatásra.',
+  'chat.runError.upstreamUnavailableMessage': 'A modellszolgáltatás átmenetileg nem érhető el — általában upstream instabilitás vagy hálózati/proxy probléma miatt. Próbáld újra egy pillanat múlva.',
+  'chat.runError.toolLoopMessage': 'A(z) {agent} ugyanazt a műveletet ismételte előrehaladás nélkül, ezért leállt. Ellenőrizd a célfájlt vagy parancsot, majd próbáld újra.',
+  'chat.runError.outputInvalidMessage': 'A modell érvénytelen kimenetet állított elő, és ez a kör megszakadt. Az újrapróbálkozás általában megoldja.',
+  'chat.runError.runtimeConfigMessage': 'A kiválasztott ügynök futásidejű konfigurációja érvénytelen, ezért a futtatás nem indulhatott el. Frissíts a legújabb verzióra, vagy fordulj a támogatáshoz.',
   'common.cancel': 'Mégse',
   'chat.selectFromLibrary': 'Importálás a könyvtárból',
   'chat.importFigma': 'Importálás Figmából',

apps/web/src/i18n/locales/id.ts

@@ -44,6 +44,21 @@ export const id: Dict = {
   'chat.runError.sourceLabel': 'Sumber kesalahan',
   'chat.runError.sourceExpandAria': 'Perluas sumber kesalahan',
   'chat.runError.sourceCollapseAria': 'Ciutkan sumber kesalahan',
+  'chat.runError.title.cliMissing': 'Agen belum terpasang',
+  'chat.runError.title.promptTooLarge': 'Input terlalu panjang',
+  'chat.runError.title.modelUnavailable': 'Model tidak tersedia',
+  'chat.runError.title.upstreamUnavailable': 'Layanan sementara tidak tersedia',
+  'chat.runError.title.toolLoop': 'Terjebak dalam perulangan',
+  'chat.runError.title.outputInvalid': 'Output model tidak valid',
+  'chat.runError.title.runtimeConfig': 'Kesalahan konfigurasi',
+  'chat.runError.cliMissingMessage': 'Alat baris perintah {agent} tidak ditemukan. Pasang dan pastikan ada di PATH, lalu coba lagi.',
+  'chat.runError.promptTooLargeMessage': 'Giliran ini melebihi batas konteks model. Perpendek prompt, hapus lampiran, atau mulai percakapan baru, lalu coba lagi.',
+  'chat.runError.modelUnavailableMessage': 'Model yang dipilih tidak tersedia atau tidak ada. Beralih ke model lain di Pengaturan, lalu coba lagi.',
+  'chat.runError.rateLimitedMessage': 'Anda telah mencapai batas penggunaan layanan model. Tunggu sebentar dan coba lagi, atau beralih ke model atau layanan lain.',
+  'chat.runError.upstreamUnavailableMessage': 'Layanan model sementara tidak tersedia — biasanya karena ketidakstabilan upstream atau masalah jaringan/proxy. Coba lagi sebentar lagi.',
+  'chat.runError.toolLoopMessage': '{agent} terus mengulang tindakan yang sama tanpa kemajuan dan dihentikan. Periksa file atau perintah target, lalu coba lagi.',
+  'chat.runError.outputInvalidMessage': 'Model menghasilkan output tidak valid dan giliran ini terhenti. Mencoba lagi biasanya memulihkannya.',
+  'chat.runError.runtimeConfigMessage': 'Konfigurasi runtime agen yang dipilih tidak valid, sehingga eksekusi tidak dapat dimulai. Perbarui ke versi terbaru atau hubungi dukungan.',
   'common.cancel': 'Batal',
   'chat.selectFromLibrary': 'Impor dari pustaka',
   'chat.importFigma': 'Impor dari Figma',