From a867595a6aac275dadb902cd75126e9355e850ea Mon Sep 17 00:00:00 2001
From: Eric Wheeler <roo-code@z.ewheeler.org>
Date: Sat, 8 Mar 2025 17:51:48 -0800
Subject: [PATCH] doc: enhance shell integration error messages

Add descriptive messages to shell integration failures to help users
understand and resolve integration issues more effectively. This improves
the debugging experience by providing specific details about why shell
integration failed.

- Add message parameter to no_shell_integration event
- Update UI to display specific error messages
- Update troubleshooting documentation link

Signed-off-by: Eric Wheeler <roo-code@z.ewheeler.org>
---
 src/core/Cline.ts                            |  4 ++--
 src/integrations/terminal/Terminal.ts        |  5 ++++-
 src/integrations/terminal/TerminalProcess.ts |  7 +++++--
 webview-ui/src/components/chat/ChatRow.tsx   | 12 +++++++-----
 4 files changed, 18 insertions(+), 10 deletions(-)

diff --git a/src/core/Cline.ts b/src/core/Cline.ts
index e7ffa5c409..b49fb60463 100644
--- a/src/core/Cline.ts
+++ b/src/core/Cline.ts
@@ -986,8 +986,8 @@ export class Cline {
 			exitDetails = details
 		})
 
-		process.once("no_shell_integration", async () => {
-			await this.say("shell_integration_warning")
+		process.once("no_shell_integration", async (message: string) => {
+			await this.say("shell_integration_warning", message)
 		})
 
 		await process
diff --git a/src/integrations/terminal/Terminal.ts b/src/integrations/terminal/Terminal.ts
index 23b999e8b8..6416cee2bd 100644
--- a/src/integrations/terminal/Terminal.ts
+++ b/src/integrations/terminal/Terminal.ts
@@ -156,7 +156,10 @@ export class Terminal {
 				})
 				.catch(() => {
 					console.log("[Terminal] Shell integration not available. Command execution aborted.")
-					process.emit("no_shell_integration")
+					process.emit(
+						"no_shell_integration",
+						"Shell integration initialization sequence '\\x1b]633;A' was not received within 4 seconds. Shell integration has been disabled for this terminal instance.",
+					)
 				})
 		})
 
diff --git a/src/integrations/terminal/TerminalProcess.ts b/src/integrations/terminal/TerminalProcess.ts
index a5376fd27c..edbfcd80c7 100644
--- a/src/integrations/terminal/TerminalProcess.ts
+++ b/src/integrations/terminal/TerminalProcess.ts
@@ -102,7 +102,7 @@ export interface TerminalProcessEvents {
 	continue: []
 	completed: [output?: string]
 	error: [error: Error]
-	no_shell_integration: []
+	no_shell_integration: [message: string]
 	/**
 	 * Emitted when a shell execution completes
 	 * @param id The terminal ID
@@ -387,7 +387,10 @@ export class TerminalProcess extends EventEmitter<TerminalProcessEvents> {
 			console.warn(
 				"[TerminalProcess] Shell integration not available. Command sent without knowledge of response.",
 			)
-			this.emit("no_shell_integration")
+			this.emit(
+				"no_shell_integration",
+				"Command was submitted; output is not available, as shell integration is inactive.",
+			)
 
 			// unknown, but trigger the event
 			this.emit(
diff --git a/webview-ui/src/components/chat/ChatRow.tsx b/webview-ui/src/components/chat/ChatRow.tsx
index 259c03fa21..cc018c162a 100644
--- a/webview-ui/src/components/chat/ChatRow.tsx
+++ b/webview-ui/src/components/chat/ChatRow.tsx
@@ -706,12 +706,14 @@ export const ChatRowContent = ({
 									</span>
 								</div>
 								<div>
-									Roo won't be able to view the command's output. Please update VSCode (
-									<code>CMD/CTRL + Shift + P</code> → "Update") and make sure you're using a supported
-									shell: zsh, bash, fish, or PowerShell (<code>CMD/CTRL + Shift + P</code> →
-									"Terminal: Select Default Profile").{" "}
+									<strong>{message.text}</strong>
+									<br />
+									<br />
+									Please update VSCode (<code>CMD/CTRL + Shift + P</code> → "Update") and make sure
+									you're using a supported shell: zsh, bash, fish, or PowerShell (
+									<code>CMD/CTRL + Shift + P</code> → "Terminal: Select Default Profile").{" "}
 									<a
-										href="https://github.com/cline/cline/wiki/Troubleshooting-%E2%80%90-Shell-Integration-Unavailable"
+										href="http://docs.roocode.com/troubleshooting/shell-integration/"
 										style={{ color: "inherit", textDecoration: "underline" }}>
 										Still having trouble?
 									</a>