Make manual handoff explicit

apps/web/src/app/inbox/page.tsx

@@ -62,6 +62,8 @@ type ConversationUiPatch = {
   optimisticLastMessage?: string;
 };
 
+const HANDOFF_REASON_FALLBACK = "Reason not provided by handoff trigger";
+
 function sortInboxConversations(
   left: { _id: string; createdAt: number; lastMessageAt?: number },
   right: { _id: string; createdAt: number; lastMessageAt?: number }
@@ -86,6 +88,13 @@ function getConversationIdentityLabel(conversation: {
   });
 }
 
+function getHandoffReasonLabel(reason: string | null | undefined): string {
+  const normalizedReason = reason?.trim();
+  return normalizedReason && normalizedReason.length > 0
+    ? normalizedReason
+    : HANDOFF_REASON_FALLBACK;
+}
+
 function InboxContent(): React.JSX.Element | null {
   const router = useRouter();
   const searchParams = useSearchParams();
@@ -1029,6 +1038,18 @@ function InboxContent(): React.JSX.Element | null {
                           </Button>
                         )}
                       </div>
+                      {selectedConversation?.aiWorkflow?.state === "handoff" && (
+                        <div
+                          className="inline-flex items-center gap-2 rounded-md border border-amber-200 bg-amber-50 px-2 py-1 text-xs text-amber-800"
+                          data-testid="inbox-handoff-context-banner"
+                        >
+                          <Bot className="h-3 w-3" />
+                          <span className="font-medium">AI handoff</span>
+                          <span className="truncate">
+                            {getHandoffReasonLabel(selectedConversation.aiWorkflow.handoffReason)}
+                          </span>
+                        </div>
+                      )}
                       {isCompactViewport && (
                         <div
                           className="flex items-center gap-2"
@@ -1500,12 +1521,27 @@ function InboxContent(): React.JSX.Element | null {
                           Loading AI responses...
                         </p>
                       ) : !orderedAiResponses || orderedAiResponses.length === 0 ? (
-                        <p
-                          className="text-sm text-muted-foreground"
-                          data-testid="inbox-ai-review-empty"
-                        >
-                          No AI responses in this conversation yet.
-                        </p>
+                        selectedConversation?.aiWorkflow?.state === "handoff" ? (
+                          <div
+                            className="space-y-2 rounded-md border border-amber-200 bg-amber-50 p-3"
+                            data-testid="inbox-ai-review-handoff-only"
+                          >
+                            <p className="text-sm font-medium text-amber-800">
+                              Conversation was handed off before an AI response record was stored.
+                            </p>
+                            <p className="text-xs text-amber-800">
+                              Handoff reason:{" "}
+                              {getHandoffReasonLabel(selectedConversation.aiWorkflow.handoffReason)}
+                            </p>
+                          </div>
+                        ) : (
+                          <p
+                            className="text-sm text-muted-foreground"
+                            data-testid="inbox-ai-review-empty"
+                          >
+                            No AI responses in this conversation yet.
+                          </p>
+                        )
                       ) : (
                         orderedAiResponses.map(
                           (response: NonNullable<typeof orderedAiResponses>[number]) => {
@@ -1627,9 +1663,10 @@ function InboxContent(): React.JSX.Element | null {
                                 {response.handedOff && (
                                   <p className="rounded bg-amber-50 px-2 py-1 text-xs text-amber-800">
                                     Handoff reason:{" "}
-                                    {response.handoffReason ??
-                                      selectedConversation?.aiWorkflow?.handoffReason ??
-                                      "Not specified"}
+                                    {getHandoffReasonLabel(
+                                      response.handoffReason ??
+                                        selectedConversation?.aiWorkflow?.handoffReason
+                                    )}
                                   </p>
                                 )}
 

apps/widget/src/components/ConversationView.test.tsx

@@ -1,4 +1,4 @@
-import { render, screen } from "@testing-library/react";
+import { fireEvent, render, screen, waitFor } from "@testing-library/react";
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import { useAction, useMutation, useQuery } from "convex/react";
 import { ConversationView } from "./ConversationView";
@@ -13,6 +13,7 @@ vi.mock("@opencom/convex", () => ({
   api: {
     messages: {
       list: "messages.list",
+      send: "messages.send",
     },
     conversations: {
       get: "conversations.get",
@@ -64,6 +65,12 @@ describe("ConversationView personas", () => {
   let messagesResult: MessageFixture[];
   let aiResponsesResult: AiResponseFixture[];
   let conversationResult: { aiWorkflowState?: "none" | "ai_handled" | "handoff" } | null;
+  let sendMessageMutationMock: ReturnType<typeof vi.fn>;
+  let identifyVisitorMutationMock: ReturnType<typeof vi.fn>;
+  let submitAiFeedbackMutationMock: ReturnType<typeof vi.fn>;
+  let handoffToHumanMutationMock: ReturnType<typeof vi.fn>;
+  let generateAiResponseActionMock: ReturnType<typeof vi.fn>;
+  let searchSuggestionsActionMock: ReturnType<typeof vi.fn>;
 
   beforeEach(() => {
     vi.clearAllMocks();
@@ -73,11 +80,40 @@ describe("ConversationView personas", () => {
     aiResponsesResult = [];
     conversationResult = { aiWorkflowState: "none" };
 
+    sendMessageMutationMock = vi.fn().mockResolvedValue(undefined);
+    identifyVisitorMutationMock = vi.fn().mockResolvedValue(undefined);
+    submitAiFeedbackMutationMock = vi.fn().mockResolvedValue(undefined);
+    handoffToHumanMutationMock = vi.fn().mockResolvedValue(undefined);
+    generateAiResponseActionMock = vi.fn().mockResolvedValue(undefined);
+    searchSuggestionsActionMock = vi.fn().mockResolvedValue([]);
+
     const mockedUseMutation = useMutation as unknown as ReturnType<typeof vi.fn>;
-    mockedUseMutation.mockReturnValue(vi.fn().mockResolvedValue(undefined));
+    mockedUseMutation.mockImplementation((mutationRef: unknown) => {
+      if (mutationRef === "messages.send") {
+        return sendMessageMutationMock;
+      }
+      if (mutationRef === "visitors.identify") {
+        return identifyVisitorMutationMock;
+      }
+      if (mutationRef === "aiAgent.submitFeedback") {
+        return submitAiFeedbackMutationMock;
+      }
+      if (mutationRef === "aiAgent.handoffToHuman") {
+        return handoffToHumanMutationMock;
+      }
+      return vi.fn().mockResolvedValue(undefined);
+    });
 
     const mockedUseAction = useAction as unknown as ReturnType<typeof vi.fn>;
-    mockedUseAction.mockReturnValue(vi.fn().mockResolvedValue([]));
+    mockedUseAction.mockImplementation((actionRef: unknown) => {
+      if (actionRef === "aiAgentActions.generateResponse") {
+        return generateAiResponseActionMock;
+      }
+      if (actionRef === "suggestions.searchForWidget") {
+        return searchSuggestionsActionMock;
+      }
+      return vi.fn().mockResolvedValue([]);
+    });
 
     const mockedUseQuery = useQuery as unknown as ReturnType<typeof vi.fn>;
     mockedUseQuery.mockImplementation((queryRef: unknown, args: unknown) => {
@@ -277,4 +313,21 @@ describe("ConversationView personas", () => {
 
     expect(screen.queryByTestId("widget-waiting-human-divider")).toBeNull();
   });
+
+  it("passes explicit handoff reason when visitor clicks talk to human", async () => {
+    renderSubject();
+
+    fireEvent.click(screen.getByTestId("widget-talk-to-human"));
+
+    await waitFor(() => {
+      expect(handoffToHumanMutationMock).toHaveBeenCalledWith(
+        expect.objectContaining({
+          conversationId: "conv_1",
+          visitorId: "visitor_1",
+          sessionToken: "wst_test",
+          reason: "Visitor clicked Talk to human button",
+        })
+      );
+    });
+  });
 });

apps/widget/src/components/ConversationView.tsx

@@ -9,6 +9,7 @@ import { useDebouncedValue } from "../hooks/useDebouncedValue";
 import { parseMarkdown } from "../utils/parseMarkdown";
 
 const DEFAULT_HUMAN_AGENT_NAME = "Support";
+const MANUAL_HANDOFF_REASON = "Visitor clicked Talk to human button";
 
 function resolveHumanAgentName(senderName?: string): string {
   const normalized = senderName?.trim();
@@ -392,6 +393,7 @@ export function ConversationView({
         conversationId,
         visitorId,
         sessionToken: sessionTokenRef.current ?? undefined,
+        reason: MANUAL_HANDOFF_REASON,
       });
     } catch (error) {
       console.error("Failed to handoff to human:", error);

packages/convex/convex/aiAgent.ts

@@ -7,6 +7,7 @@ import {
   type MutationCtx,
   type QueryCtx,
 } from "./_generated/server";
+import { internal } from "./_generated/api";
 import { Doc, Id } from "./_generated/dataModel";
 import { getAuthenticatedUserFromSession } from "./auth";
 import { getWorkspaceMembership, requirePermission } from "./permissions";
@@ -646,25 +647,44 @@ export const handoffToHuman = mutation({
     const handoffMessage =
       settings?.handoffMessage ?? "Let me connect you with a human agent who can help you better.";
 
+    const now = Date.now();
+
     const messageId: Id<"messages"> = await ctx.db.insert("messages", {
       conversationId: args.conversationId,
       senderId: "ai-agent",
       content: handoffMessage,
       senderType: "bot",
-      createdAt: Date.now(),
+      createdAt: now,
     });
 
-    const now = Date.now();
-
     // Update conversation to ensure it's open and visible to agents
     await ctx.db.patch(args.conversationId, {
       status: "open",
       updatedAt: now,
+      lastMessageAt: now,
+      // Preserve existing visitor-unread count while ensuring handoff-only threads surface to agents.
+      unreadByAgent: Math.max(conversation.unreadByAgent || 0, 1),
       aiWorkflowState: "handoff",
       aiHandoffReason: args.reason,
       aiLastResponseAt: now,
     });
 
+    await ctx.scheduler.runAfter(0, internal.notifications.routeEvent, {
+      eventType: "chat_message",
+      domain: "chat",
+      audience: "agent",
+      workspaceId: conversation.workspaceId,
+      actorType: "bot",
+      conversationId: args.conversationId,
+      title: "AI handoff",
+      body: handoffMessage,
+      data: {
+        conversationId: args.conversationId,
+        type: "ai_handoff",
+      },
+      eventKey: `chat_handoff:${messageId}`,
+    });
+
     return { messageId, handoffMessage };
   },
 });

packages/convex/tests/aiAgentHandoffPath.test.ts

@@ -7,5 +7,13 @@ describe("aiAgent.handoffToHuman persistence path", () => {
 
     expect(source).toContain('senderId: "ai-agent"');
     expect(source).not.toContain('senderId: "system"');
+    expect(source).toContain("const now = Date.now();");
+    expect(source).toContain("createdAt: now");
+    expect(source).toContain("lastMessageAt: now");
+    expect(source).toMatch(
+      /unreadByAgent:\s*Math\.max\(\s*conversation\.unreadByAgent\s*\|\|\s*0,\s*1\s*\)/
+    );
+    expect(source).toContain("internal.notifications.routeEvent");
+    expect(source).toContain('audience: "agent"');
   });
 });