feat: add retry logic and better error messages for reply commands

Based on investigation showing race conditions and UI state conflicts
causing intermittent reply failures:

- Add withRetry() helper for exponential backoff (3 attempts, 500ms base)
- Add error field to ReplyResult interface
- Provide descriptive error messages for each failure point
- Display error details in CLI and MCP tool outputs

This helps diagnose failures caused by:
- Existing compose windows blocking UI
- Draft recovery overlays
- Reply button not immediately interactable

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: edwinhu

src/cli.ts

@@ -859,7 +859,7 @@ async function cmdReply(options: CliOptions) {
       success(`Draft saved (${result.draftId})`);
     }
   } else {
-    error("Failed to create reply");
+    error(result.error || "Failed to create reply");
   }
 
   await disconnect(conn);
@@ -890,7 +890,7 @@ async function cmdReplyAll(options: CliOptions) {
       success(`Draft saved (${result.draftId})`);
     }
   } else {
-    error("Failed to create reply-all");
+    error(result.error || "Failed to create reply-all");
   }
 
   await disconnect(conn);
@@ -928,7 +928,7 @@ async function cmdForward(options: CliOptions) {
       success(`Draft saved (${result.draftId})`);
     }
   } else {
-    error("Failed to create forward");
+    error(result.error || "Failed to create forward");
   }
 
   await disconnect(conn);

src/mcp/tools.ts

@@ -636,7 +636,7 @@ export async function replyHandler(args: z.infer<typeof ReplySchema>): Promise<T
     const result = await replyToThread(conn, args.threadId, args.body, send);
 
     if (!result.success) {
-      throw new Error("Failed to create reply");
+      throw new Error(result.error || "Failed to create reply");
     }
 
     if (send) {
@@ -668,7 +668,7 @@ export async function replyAllHandler(args: z.infer<typeof ReplyAllSchema>): Pro
     const result = await replyAllToThread(conn, args.threadId, args.body, send);
 
     if (!result.success) {
-      throw new Error("Failed to create reply-all");
+      throw new Error(result.error || "Failed to create reply-all");
     }
 
     if (send) {
@@ -700,7 +700,7 @@ export async function forwardHandler(args: z.infer<typeof ForwardSchema>): Promi
     const result = await forwardThread(conn, args.threadId, args.toEmail, args.body, send);
 
     if (!result.success) {
-      throw new Error("Failed to create forward");
+      throw new Error(result.error || "Failed to create forward");
     }
 
     if (send) {

src/reply.ts

@@ -20,6 +20,7 @@ import {
 export interface ReplyResult {
   success: boolean;
   draftId?: string;
+  error?: string;
 }
 
 /**
@@ -32,39 +33,71 @@ async function completeDraft(
 ): Promise<ReplyResult> {
   if (send) {
     const sent = await sendDraft(conn);
-    return { success: sent };
+    if (!sent) {
+      return { success: false, error: "Failed to send draft" };
+    }
+    return { success: true };
   }
 
   const saved = await saveDraft(conn);
-  return { success: saved, draftId: draftKey };
+  if (!saved) {
+    return { success: false, error: "Failed to save draft" };
+  }
+  return { success: true, draftId: draftKey };
+}
+
+/**
+ * Retry a function with exponential backoff
+ */
+async function withRetry<T>(
+  fn: () => Promise<T | null>,
+  maxRetries: number = 3,
+  baseDelay: number = 500
+): Promise<T | null> {
+  for (let attempt = 0; attempt < maxRetries; attempt++) {
+    const result = await fn();
+    if (result !== null) {
+      return result;
+    }
+    if (attempt < maxRetries - 1) {
+      const delay = baseDelay * Math.pow(2, attempt);
+      await new Promise(r => setTimeout(r, delay));
+    }
+  }
+  return null;
 }
 
 /**
  * Reply to a thread
  *
  * Uses Superhuman's native REPLY_POP_OUT command which properly sets up
  * threading (threadId, inReplyTo, references), recipients, and subject.
+ * Includes retry logic for transient UI state failures.
  *
  * @param conn - The Superhuman connection
  * @param threadId - The thread ID to reply to
  * @param body - The reply body text
  * @param send - If true, send immediately; if false, save as draft
- * @returns Result with success status and optional draft ID
+ * @returns Result with success status, optional draft ID, and error message if failed
  */
 export async function replyToThread(
   conn: SuperhumanConnection,
   threadId: string,
   body: string,
   send: boolean = false
 ): Promise<ReplyResult> {
-  const draftKey = await openReplyCompose(conn, threadId);
+  // Retry opening compose in case of transient UI state issues
+  const draftKey = await withRetry(() => openReplyCompose(conn, threadId), 3, 500);
   if (!draftKey) {
-    return { success: false };
+    return {
+      success: false,
+      error: "Failed to open reply compose (UI may be blocked by existing compose window or overlay)"
+    };
   }
 
   const bodySet = await setBody(conn, textToHtml(body));
   if (!bodySet) {
-    return { success: false };
+    return { success: false, error: "Failed to set reply body" };
   }
 
   return completeDraft(conn, draftKey, send);
@@ -75,28 +108,32 @@ export async function replyToThread(
  *
  * Uses Superhuman's native REPLY_ALL_POP_OUT command which properly sets up
  * threading (threadId, inReplyTo, references), all recipients (To and Cc),
- * and subject automatically.
+ * and subject automatically. Includes retry logic for transient UI state failures.
  *
  * @param conn - The Superhuman connection
  * @param threadId - The thread ID to reply to
  * @param body - The reply body text
  * @param send - If true, send immediately; if false, save as draft
- * @returns Result with success status and optional draft ID
+ * @returns Result with success status, optional draft ID, and error message if failed
  */
 export async function replyAllToThread(
   conn: SuperhumanConnection,
   threadId: string,
   body: string,
   send: boolean = false
 ): Promise<ReplyResult> {
-  const draftKey = await openReplyAllCompose(conn, threadId);
+  // Retry opening compose in case of transient UI state issues
+  const draftKey = await withRetry(() => openReplyAllCompose(conn, threadId), 3, 500);
   if (!draftKey) {
-    return { success: false };
+    return {
+      success: false,
+      error: "Failed to open reply-all compose (UI may be blocked by existing compose window or overlay)"
+    };
   }
 
   const bodySet = await setBody(conn, textToHtml(body));
   if (!bodySet) {
-    return { success: false };
+    return { success: false, error: "Failed to set reply body" };
   }
 
   return completeDraft(conn, draftKey, send);
@@ -107,13 +144,14 @@ export async function replyAllToThread(
  *
  * Uses Superhuman's native FORWARD_POP_OUT command which properly sets up
  * the forwarded message content, subject, and formatting.
+ * Includes retry logic for transient UI state failures.
  *
  * @param conn - The Superhuman connection
  * @param threadId - The thread ID to forward
  * @param toEmail - The email address to forward to
  * @param body - The message body to include before the forwarded content
  * @param send - If true, send immediately; if false, save as draft
- * @returns Result with success status and optional draft ID
+ * @returns Result with success status, optional draft ID, and error message if failed
  */
 export async function forwardThread(
   conn: SuperhumanConnection,
@@ -122,20 +160,24 @@ export async function forwardThread(
   body: string,
   send: boolean = false
 ): Promise<ReplyResult> {
-  const draftKey = await openForwardCompose(conn, threadId);
+  // Retry opening compose in case of transient UI state issues
+  const draftKey = await withRetry(() => openForwardCompose(conn, threadId), 3, 500);
   if (!draftKey) {
-    return { success: false };
+    return {
+      success: false,
+      error: "Failed to open forward compose (UI may be blocked by existing compose window or overlay)"
+    };
   }
 
   const recipientAdded = await addRecipient(conn, toEmail);
   if (!recipientAdded) {
-    return { success: false };
+    return { success: false, error: "Failed to add forward recipient" };
   }
 
   if (body) {
     const bodySet = await setBody(conn, textToHtml(body));
     if (!bodySet) {
-      return { success: false };
+      return { success: false, error: "Failed to set forward body" };
     }
   }