fix(drive-integration): show actionable error when app not installed in environment []

[Mitch Goudy (mgoudy91)]

Problem

When a Google Drive import fails due to the app not being installed in a space, users see a generic "This preview could not be completed. Please start again." message with no actionable guidance.

Fix

Adds frontend handling for two new failure codes surfaced by agents-api:

• app-not-installed — shown when the app is not installed in the space (after the master env fallback in agents-api also finds nothing). Message: "The Drive Integration app is not installed in this space. Install it via Apps > Manage apps and try again."
• ai-service-unavailable — shown when the AI service is temporarily unavailable. Message: "The AI service is temporarily unavailable. Please try again in a few minutes."

Both codes are handled in useWorkflowAgent, WorkflowFailureReason, and ModalOrchestrator.

Test plan

• Verify APP_NOT_INSTALLED error modal appears with correct title and message
• Verify AI_SERVICE_UNAVAILABLE error modal appears with correct title and message
• Verify generic error still shows for unrecognized failure codes

Related: contentful/agents-api#615

🤖 Generated with Claude Code

[Josh Lewis (lewisjcs)]

⚔️ The Gauntlet — 🛡️ 0 Blockers · 3 advisory

_{🤖 AI-powered · your code, through the lanes}

🛑 Blockers	0
⚠️ Concerns	2
💡 Nits	1
🔒 Security	clean ✓
🧪 Lanes	code-quality · adversarial · security

Findings

	Finding	Location	Status
⚠️	APP_NOT_INSTALLED copy tells users to reinstall an installed app when ext-api returns a transient 502. agents-api#615 maps 404 || 502 to the same app-not-installed code, but 502 is BadGatewayError (infra), not "not installed". Frontend lever: soften the copy so it covers the transient case. Root fix: stop mapping 502 → app-not-installed in #615.	messages.ts:15	Open
⚠️	Modal title says "environment", body says "space" for the same error — two different scoping words in one modal. Root cause is environment-scoped (the master-alias fallback), so "environment" is the more accurate term. Pick one and use it in both.	ModalOrchestrator.tsx:196 ↔ messages.ts:15	Open
💡	No unit test for the new code → reason → message mapping. It's a cross-service string contract; a typo silently falls through to GENERIC. Add a test asserting 'app-not-installed' / 'ai-service-unavailable' map to the right reason + message.	useWorkflowAgent.ts:130	Open

One thing worth confirming: is there a throw site for PREVIEW_AGENT_FAILED (which #615 maps to ai-service-unavailable)? It wasn't found in #615's diff, so the ai-service-unavailable half of this PR may be inert until a later producer change lands. Not a blocker — just worth a sanity check.

🤖 Machine-readable findings (for agents)

{
  "tool": "gauntlet",
  "schema": "v1",
  "reviewed_ref": "3b21947",
  "verdict": { "blockers": 0, "concerns": 2, "nits": 1, "security": "clean" },
  "findings": [
    { "severity": "concern", "location": "apps/drive-integration/src/utils/constants/messages.ts:15", "lens": "adversarial-review / Failure Scenarios", "confidence": 90, "claim": "APP_NOT_INSTALLED copy is shown on a transient ext-api 502 (agents-api#615 maps 404||502 to app-not-installed), telling users to reinstall an installed app.", "recommendation": "Soften the frontend copy to cover the transient case; fix the root cause in agents-api#615 by not mapping 502 to app-not-installed." },
    { "severity": "concern", "location": "apps/drive-integration/src/locations/Page/components/mainpage/ModalOrchestrator.tsx:196", "lens": "adversarial-review / Hidden Assumptions", "confidence": 92, "claim": "Modal title says 'environment' while body copy says 'space' for the same APP_NOT_INSTALLED error.", "recommendation": "Use one consistent term in title and body; 'environment' matches the root cause." },
    { "severity": "nit", "location": "apps/drive-integration/src/hooks/useWorkflowAgent.ts:130", "lens": "code-quality-standards / Gaps", "confidence": 80, "claim": "No unit test covers the new code->reason->message mapping across the cross-service string contract.", "recommendation": "Add a unit test asserting app-not-installed and ai-service-unavailable map to the correct reason and message." }
  ]
}

---

_{🎮 The Gauntlet · an AI review harness built by Josh C.S. Lewis · reviewed at 3b21947. Everything but the 🛑 is advisory.}