Make manual handoff explicit by djanogly · Pull Request #10 · opencom-org/opencom

djanogly · 2026-03-05T10:41:34Z

This pull request introduces improvements to the AI handoff workflow and enhances both backend logic and frontend user experience. The changes ensure that a clear handoff reason is recorded and displayed when a visitor requests to talk to a human, and that the backend properly updates conversation status and notifies agents. Additionally, the test suite is updated to verify the new behavior.

AI Handoff Workflow and Reason Handling

When a visitor clicks the "Talk to human" button, the frontend now passes an explicit handoff reason ("Visitor clicked Talk to human button") to the backend when triggering the handoff mutation (MANUAL_HANDOFF_REASON in ConversationView.tsx). [1] [2]
The backend mutation handoffToHuman now updates the conversation fields: sets lastMessageAt, increments unreadByAgent, and triggers an internal notification to alert agents of the new message.
Tests are added and updated to verify that the handoff reason is passed correctly and that the backend updates and notification logic are present. [1] [2]

Frontend UI Improvements

The inbox page now displays a banner with the handoff reason when a conversation is in the "handoff" state, providing clear context to users.
If a conversation was handed off before any AI response was stored, a dedicated message is shown explaining the handoff and its reason.

Test Suite Enhancements

Test mocks for mutations and actions are refactored for clarity and to support the new handoff logic, improving test reliability and maintainability. [1] [2]

vercel · 2026-03-05T10:41:39Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
opencom-landing	Ready	Preview, Comment	Mar 5, 2026 11:19am
opencom-web	Ready	Preview, Comment	Mar 5, 2026 11:19am

Copilot

Pull request overview

This PR makes manual AI→human handoffs more explicit by sending and surfacing a clear handoff reason, while also updating backend persistence behavior and extending tests/UI to reflect the new handoff context.

Changes:

Widget now passes an explicit reason when the visitor clicks “Talk to human”.
Backend handoffToHuman updates conversation metadata (lastMessageAt, unreadByAgent) and schedules a notification.
Inbox UI displays handoff context (banner + empty-AI-review handoff explanation), and tests are updated accordingly.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
packages/convex/convex/aiAgent.ts	Updates handoff mutation to patch conversation metadata and attempt to notify on handoff.
packages/convex/tests/aiAgentHandoffPath.test.ts	Adds assertions to ensure the new persistence/notification behavior exists in source.
apps/widget/src/components/ConversationView.tsx	Sends explicit handoff reason for the manual “Talk to human” action.
apps/widget/src/components/ConversationView.test.tsx	Refactors action/mutation mocks and adds a test asserting the explicit reason is passed.
apps/web/src/app/inbox/page.tsx	Shows handoff reason context in the inbox header and AI review panel.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-03-05T10:47:50Z

packages/convex/convex/aiAgent.ts

+    await ctx.scheduler.runAfter(0, internal.notifications.notifyNewMessage, {
+      conversationId: args.conversationId,
+      messageContent: handoffMessage,
+      senderType: "bot",
+      messageId,
+      senderId: "ai-agent",
+      sentAt: now,
+      channel: "chat",
+    });
+


internal.notifications.notifyNewMessage only notifies agents when senderType === "visitor"; when senderType is "bot" it routes notifications to the visitor instead (push/email). As written, the handoff will likely notify the visitor (potentially redundantly) and won’t alert agents about the handoff/new message. Consider routing an agent-facing event explicitly (e.g., internal.notifications.routeEvent with audience: "agent") or extending notifications to support an agent-notify mode for bot/handoff events, rather than calling notifyNewMessage with senderType: "bot".

Suggested change

await ctx.scheduler.runAfter(0, internal.notifications.notifyNewMessage, {

conversationId: args.conversationId,

messageContent: handoffMessage,

senderType: "bot",

messageId,

senderId: "ai-agent",

sentAt: now,

channel: "chat",

});

await ctx.scheduler.runAfter(0, internal.notifications.routeEvent, {

conversationId: args.conversationId,

audience: "agent",

type: "new_message",

messageId,

sentAt: now,

});

Copilot · 2026-03-05T10:47:51Z

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

    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);
+    });


This useMutation mockImplementation expects mutationRef === "messages.send" to return sendMessageMutationMock, but the @opencom/convex mock in this test file doesn’t define api.messages.send (only messages.list). That means the component will call useMutation(undefined) and this branch will never match, so sendMessageMutationMock is unused and the test setup diverges from real usage. Add messages.send: "messages.send" to the mocked api object so the mutation ref mapping is exercised correctly.

Copilot · 2026-03-05T10:47:51Z

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

+                          <span className="truncate">
+                            {selectedConversation.aiWorkflow.handoffReason ??
+                              "Reason not provided by handoff trigger"}
+                          </span>


The fallback copy "Reason not provided by handoff trigger" is duplicated in multiple UI spots (banner + AI review empty state). Consider centralizing this string (e.g., a constant/helper) so future copy changes stay consistent across the inbox UI.

Copilot

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 2 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-03-05T11:04:15Z

packages/convex/convex/aiAgent.ts

      status: "open",
      updatedAt: now,
+      lastMessageAt: now,
+      unreadByAgent: (conversation.unreadByAgent || 0) + 1,
      aiWorkflowState: "handoff",


lastMessageAt/updatedAt are set from now, but the inserted handoff message uses its own Date.now() value for createdAt. This can create small ordering inconsistencies (conversation sorted by lastMessageAt slightly after the message timestamp). Consider capturing a single timestamp once and using it for both the message createdAt and the conversation patch fields.

Copilot · 2026-03-05T11:04:15Z

packages/convex/tests/aiAgentHandoffPath.test.ts

    expect(source).toContain('senderId: "ai-agent"');
    expect(source).not.toContain('senderId: "system"');
+    expect(source).toContain("lastMessageAt: now");
+    expect(source).toContain("unreadByAgent: (conversation.unreadByAgent || 0) + 1");


This test is asserting an exact source-code substring for the unreadByAgent update expression. That makes the test very sensitive to harmless refactors/formatting changes (e.g., switching to ??, adding whitespace, or extracting a helper) while not actually validating runtime behavior. Consider loosening the assertion (e.g., check for unreadByAgent: and + 1 separately / use a regex) or adding an integration-style assertion that the mutation actually increments unreadByAgent and updates lastMessageAt.

Suggested change

expect(source).toContain("unreadByAgent: (conversation.unreadByAgent || 0) + 1");

expect(source).toMatch(/unreadByAgent:\s*[^+]*\+\s*1/);

Make manual handoff explicit

28809fe

djanogly requested a review from Copilot March 5, 2026 10:41

Copilot started reviewing on behalf of djanogly March 5, 2026 10:42 View session

Copilot AI reviewed Mar 5, 2026

View reviewed changes

address small comments

6fb872f

vercel bot deployed to Preview – opencom-landing March 5, 2026 11:00 View deployment

djanogly requested a review from Copilot March 5, 2026 11:00

Copilot started reviewing on behalf of djanogly March 5, 2026 11:00 View session

vercel bot deployed to Preview – opencom-web March 5, 2026 11:01 View deployment

Copilot AI reviewed Mar 5, 2026

View reviewed changes

Fixes

ba8017b

vercel bot deployed to Preview – opencom-landing March 5, 2026 11:18 View deployment

vercel bot deployed to Preview – opencom-web March 5, 2026 11:19 View deployment

djanogly merged commit 80a56a8 into main Mar 5, 2026
4 of 5 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Make manual handoff explicit#10

Make manual handoff explicit#10
djanogly merged 3 commits intomainfrom
pr/improve-ai-handoff

djanogly commented Mar 5, 2026

Uh oh!

vercel bot commented Mar 5, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Mar 5, 2026

Uh oh!

Copilot AI Mar 5, 2026

Uh oh!

Copilot AI Mar 5, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Mar 5, 2026

Uh oh!

Copilot AI Mar 5, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	expect(source).toContain("unreadByAgent: (conversation.unreadByAgent \|\| 0) + 1");
	expect(source).toMatch(/unreadByAgent:\s[^+]\+\s*1/);

Conversation

djanogly commented Mar 5, 2026

Uh oh!

vercel bot commented Mar 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Mar 5, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 5, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 5, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Mar 5, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 5, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

vercel bot commented Mar 5, 2026 •

edited

Loading