Handoff UX improvements

Author: djanogly

apps/widget/src/components/ConversationView.tsx

@@ -1,4 +1,4 @@
-import { useState, useEffect, useRef } from "react";
+import { useState, useEffect, useMemo, useRef } from "react";
 import { useQuery, useMutation, useAction } from "convex/react";
 import { api } from "@opencom/convex";
 import type { Id } from "@opencom/convex/dataModel";
@@ -373,6 +373,36 @@ export function ConversationView({
     }
   };
 
+  const showWaitingForHumanSupport = useMemo(() => {
+    if (!messages || messages.length === 0 || !aiResponses || aiResponses.length === 0) {
+      return false;
+    }
+
+    const handoffMessageIds = new Set(
+      aiResponses
+        .filter((response: { handedOff?: boolean; messageId: string }) => response.handedOff)
+        .map((response: { messageId: string }) => response.messageId)
+    );
+    if (handoffMessageIds.size === 0) {
+      return false;
+    }
+
+    let lastHandoffMessageIndex = -1;
+    for (let i = messages.length - 1; i >= 0; i -= 1) {
+      if (handoffMessageIds.has(messages[i]._id)) {
+        lastHandoffMessageIndex = i;
+        break;
+      }
+    }
+    if (lastHandoffMessageIndex < 0) {
+      return false;
+    }
+
+    return !messages
+      .slice(lastHandoffMessageIndex + 1)
+      .some((message) => message.senderType === "agent" || message.senderType === "user");
+  }, [aiResponses, messages]);
+
   const dismissCsatPrompt = () => {
     setCsatPromptVisible(false);
     setDismissedCsatByConversation((prev) => ({ ...prev, [conversationKey]: true }));
@@ -516,6 +546,11 @@ export function ConversationView({
             }
           )
         )}
+        {showWaitingForHumanSupport && (
+          <div className="opencom-status-divider" data-testid="widget-waiting-human-divider">
+            Waiting for human support
+          </div>
+        )}
         {isAiTyping && (
           <div className="opencom-message opencom-message-agent opencom-message-ai opencom-typing">
             <span className="opencom-ai-badge">

apps/widget/src/styles.css

@@ -253,6 +253,25 @@
   font-weight: 500;
 }
 
+.opencom-status-divider {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  color: var(--opencom-text-muted);
+  font-size: 11px;
+  font-weight: 500;
+  text-align: center;
+  margin: 4px 0;
+}
+
+.opencom-status-divider::before,
+.opencom-status-divider::after {
+  content: "";
+  flex: 1;
+  height: 1px;
+  background: color-mix(in srgb, var(--opencom-text-muted) 25%, transparent);
+}
+
 .opencom-message {
   max-width: 80%;
   padding: 12px 16px;

packages/convex/convex/aiAgentActions.ts

@@ -538,6 +538,42 @@ export const generateResponse = action({
       title: r.title,
     }));
 
+    if (handoff) {
+      // Persist only the precanned handoff message so visitors see one assistant message.
+      const handoffResult = await ctx.runMutation(api.aiAgent.handoffToHuman, {
+        conversationId: args.conversationId,
+        visitorId: args.visitorId,
+        sessionToken: args.sessionToken,
+        reason: handoffReason ?? undefined,
+      });
+
+      await ctx.runMutation(api.aiAgent.storeResponse, {
+        conversationId: args.conversationId,
+        visitorId: args.visitorId,
+        sessionToken: args.sessionToken,
+        messageId: handoffResult.messageId,
+        query: args.query,
+        response: handoffResult.handoffMessage,
+        sources: [],
+        confidence,
+        handedOff: true,
+        handoffReason: handoffReason ?? undefined,
+        generationTimeMs,
+        tokensUsed,
+        model: settings.model,
+        provider,
+      });
+
+      return {
+        response: handoffResult.handoffMessage,
+        confidence,
+        sources: [],
+        handoff: true,
+        handoffReason,
+        messageId: handoffResult.messageId,
+      };
+    }
+
     // Create the AI message via the internal bot-only path.
     const messageId = await ctx.runMutation(internal.messages.internalSendBotMessage, {
       conversationId: args.conversationId,
@@ -555,30 +591,19 @@ export const generateResponse = action({
       response: responseText,
       sources,
       confidence,
-      handedOff: handoff,
-      handoffReason: handoffReason ?? undefined,
+      handedOff: false,
       generationTimeMs,
       tokensUsed,
       model: settings.model,
       provider,
     });
 
-    // If handoff is needed, trigger it
-    if (handoff) {
-      await ctx.runMutation(api.aiAgent.handoffToHuman, {
-        conversationId: args.conversationId,
-        visitorId: args.visitorId,
-        sessionToken: args.sessionToken,
-        reason: handoffReason ?? undefined,
-      });
-    }
-
     return {
       response: responseText,
       confidence,
       sources,
-      handoff,
-      handoffReason,
+      handoff: false,
+      handoffReason: null,
       messageId,
     };
   },

packages/convex/tests/aiAgentRuntimeSafety.test.ts

@@ -362,6 +362,84 @@ describe("aiAgentActions runtime safety", () => {
     );
   });
 
+  it("stores only the handoff message when AI output requires a handoff", async () => {
+    const handoffMessage = "Let me connect you with a human agent who can help you better.";
+    mockGenerateText.mockResolvedValue({
+      text: "I don't have enough information to answer that question. Let me connect you with a human agent.",
+      usage: { totalTokens: 33 },
+    } as any);
+
+    const runQuery = vi.fn(async (_reference: unknown, args: Record<string, unknown>) => {
+      if ("query" in args) {
+        return [];
+      }
+      if ("workspaceId" in args && "conversationId" in args === false) {
+        return {
+          enabled: true,
+          model: "openai/gpt-5-nano",
+          confidenceThreshold: 0.2,
+          knowledgeSources: ["articles"],
+          personality: null,
+        };
+      }
+      return {
+        conversationId: "conversation_1",
+        workspaceId: "workspace_1",
+        visitorId: "visitor_1",
+      };
+    });
+
+    const runMutation = vi.fn(async (_reference: unknown, args: Record<string, unknown>) => {
+      if (Object.keys(args).length === 1 && "workspaceId" in args) {
+        return "cleared";
+      }
+      if ("reason" in args) {
+        return {
+          messageId: "handoff_message_single_1",
+          handoffMessage,
+        };
+      }
+      if ("query" in args && "response" in args) {
+        return "ai_response_handoff_1";
+      }
+      if ("senderId" in args && "content" in args) {
+        throw new Error("Unexpected AI message persistence before handoff");
+      }
+      throw new Error(`Unexpected mutation args: ${JSON.stringify(args)}`);
+    });
+
+    const result = await generateResponse._handler(
+      {
+        runQuery,
+        runMutation,
+      } as any,
+      {
+        workspaceId: "workspace_1" as any,
+        conversationId: "conversation_1" as any,
+        query: "Who should I vote for?",
+      }
+    );
+
+    expect(result.handoff).toBe(true);
+    expect(result.messageId).toBe("handoff_message_single_1");
+    expect(result.response).toBe(handoffMessage);
+    expect(runMutation).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.objectContaining({
+        query: "Who should I vote for?",
+        response: handoffMessage,
+        messageId: "handoff_message_single_1",
+        handedOff: true,
+      })
+    );
+    expect(runMutation).not.toHaveBeenCalledWith(
+      expect.anything(),
+      expect.objectContaining({
+        senderId: "ai-agent",
+      })
+    );
+  });
+
   it("persists a handoff message when generation fails", async () => {
     mockGenerateText.mockRejectedValue(new Error("gateway timeout"));