Duplicate messages with stuck streaming state after tool approval (saveStreamDeltas)

[christiannwamba]

Summary

When using @convex-dev/agent with useUIMessages hook and saveStreamDeltas: true, approving or denying a tool call results in duplicate assistant messages appearing in the UI:

1. Stream delta message: Partial/incomplete text, stuck with status: "streaming" even after stream completes, ID has "stream" prefix
2. MessageDoc: Complete text with status: "success", regular message ID

Closing and reopening the UI component makes the duplicate disappear and shows only the correct complete message.

Environment

• @convex-dev/agent: 0.3.0
• ai: 5.0.51
• React Native mobile app
• Using useUIMessages hook with stream: true
• Backend uses thread.streamText() with saveStreamDeltas: true

Reproduction Steps

1. Set up agent with human-in-the-loop tool approval flow
2. User sends message that triggers a tool call (e.g., "Schedule a meeting")
3. Assistant responds with tool-call, approval UI shows
4. User approves or denies the tool call
5. Backend saves tool result message to thread using chatAgent.saveMessage()
6. Backend calls thread.streamText() with contextOptions: { recentMessages: 20 } and saveStreamDeltas: true
7. Stream completes successfully on backend
8. Frontend shows two assistant messages instead of one

Expected Behavior

After tool approval, there should be one assistant message responding to the tool result with:

• Full text content
• status: "success" (or appropriate final status)
• Single message ID

Actual Behavior

Two assistant messages appear:

1. Stream delta (incomplete/stuck):

   • Text is incomplete or partial
   • status: "streaming" (never transitions to "finished")
   • ID has "stream" prefix

2. MessageDoc (complete):

   • Full text content
   • status: "success"
   • Regular message ID

Key Observations

Backend Logs Show Correct Behavior

[STREAM_FINISH] Stream completed: { threadId, responseMessages: 1, finishReason: 'stop' }
[STREAM_DONE] Stream consumed

[TOOL_RESULT] All messages AFTER stream: [
  { id: 'ks75jy3hx8gasg180f2mawxxrs7vdn5g', role: 'assistant', status: 'success', order: 0, stepOrder: 3 },
  { id: 'ks71dp83bxp9wtby4xtpdw6wz17vdyfb', role: 'tool', status: 'success', order: 0, stepOrder: 2 },
  { id: 'ks7av80wa18h4h7q9zebr3rgp17vdzpe', role: 'assistant', status: 'success', order: 0, stepOrder: 1 },
  { id: 'ks71qdg4fkvtv8zn24zhx8cxvx7vc2d5', role: 'user', status: 'success', order: 0, stepOrder: 0 }
]

✓ Backend has only ONE assistant message at stepOrder=3
✓ Status is correctly "success"
✓ Stream consumed successfully

Frontend Receives Duplicate

useUIMessages returns two messages:

• One with "stream" prefix ID - partial/stuck at "streaming"
• One with regular message ID - complete with "success"

Workaround That Proves It's Client-Side State Issue

Closing and reopening the UI component fixes the issue immediately.

This proves:

• Backend data is correct (otherwise reopening wouldn't fix it)
• Problem is in useUIMessages internal state management
• Stream deltas are persisting in component state after stream finishes

Suspected Root Cause

When saveStreamDeltas: true is used:

1. Stream deltas are saved to streamingMessages table during streaming
2. useUIMessages merges these deltas with MessageDoc objects
3. After stream finishes, the stream delta state doesn't update from "streaming" to "finished"
4. Frontend continues showing both:
   • The stream delta (status: "streaming", partial text)
   • The MessageDoc (status: "success", complete text)
5. Remounting the component reinitializes useUIMessages state, fetching fresh data and correctly showing only the MessageDoc

Additional Context

Backend Tool Result Flow

// 1. Build and save tool result message
const toolMessage = await buildToolResultMessage(ctx, input, approvalTools, spanTracker);
await chatAgent.saveMessage(ctx, { threadId, message: toolMessage });

// 2. Start new stream (no messages parameter, let context fetch from thread)
const result = await thread.streamText({
  model: "openai/gpt-4.1",
  system: systemPrompt,
  tools,
  // ... callbacks
}, {
  saveStreamDeltas: true,
  contextOptions: {
    recentMessages: 20,
  },
});

await result.consumeStream();

Frontend Query

// domains/chat/api.chat.ts
export const listThreadMessages = authorizedQuery({
  handler: async (ctx, { threadId, paginationOpts, streamArgs }) => {
    const paginated = await listUIMessages(ctx, components.agent, {
      threadId,
      paginationOpts,
    });

    const streams = await chatAgent.syncStreams(ctx, {
      threadId,
      streamArgs,
    });

    return { ...paginated, streams };
  },
});

// Frontend
const uiMessagesResult = useUIMessages(
  api.app.chat.listThreadMessages,
  { threadId },
  {
    initialNumItems: 50,
    stream: true,
  },
);

Temporary Workarounds Tried

1. ❌ Filtering finished streams on backend
2. ❌ Aborting old streams before new stream
3. ❌ Updating message status before streaming
4. ✓ Disabling saveStreamDeltas: Fixes the issue but loses real-time streaming feature

[christiannwamba]

I implemented a client-side workaround that preserves real-time streaming while preventing duplicate messages.

Added deduplication logic in the message transform hook that:

1. Groups messages by content - Messages with the same role and similar text are grouped together
2. Prioritizes intelligently:
   • If both completed AND streaming exist → use completed (stuck delta scenario)
   • If only streaming exists → use streaming (active streaming)
   • If only completed exists → use completed

import { useMemo } from "react";
import type { UIMessage } from "@convex-dev/agent/react";

export function useMessageTransform(uiMessages: UIMessage[]) {
  const transformedMessages = useMemo(() => {
    // Group messages by their base content to detect duplicates
    const messageGroups = new Map<string, UIMessage[]>();
    
    uiMessages.forEach((m) => {
      const text = extractMessageText(m);
      const key = `${m.role}-${text.substring(0, 50)}`;
      
      if (!messageGroups.has(key)) {
        messageGroups.set(key, []);
      }
      messageGroups.get(key)!.push(m);
    });

    // For each group, prefer completed messages over streaming deltas
    const deduplicatedMessages = Array.from(messageGroups.values()).map(group => {
      const streaming = group.find((m) => m.status === "streaming");
      const completed = group.find((m) => m.status === "success");

      // If both exist, the stream delta is stuck - use completed
      if (completed && streaming) {
        return completed;
      }

      // Active streaming, preserve it
      if (streaming) {
        return streaming;
      }

      // Only completed exists
      if (completed) {
        return completed;
      }

      // Fallback
      return group[0];
    });

    return deduplicatedMessages;
  }, [uiMessages]);

  return transformedMessages;
}

Some trade offs to keep in mind:

• Adds complexity to client-side message handling
• Relies on heuristics (first 50 chars of text) for grouping
• Doesn't fix the root cause (stream delta state not transitioning)

[ianmacartney]

Thanks for the detailed report!
The logic in dedupeMessages is supposed to be preferring the completed message. I wonder why it's not...
Can you use useUIMessages with {stream: false} and useStreamingUIMessages separately (pointing at the same query) and see what the messages are when it's duplicated? In particular:

• What are the order & stepOrder for the messages that are supposed to match
• What are the statuses of these messages?
• Does useStreamingUIMessages work correctly otherwise in these cases? i.e. does the status & behavior match non-tool-result streaming responses?
• Does useThreadMessages work in this case (on a query with listMessages not listUIMessages)?

[ianmacartney]

@christiannwamba I also would love to know answers to the above questions to help figure out the root cause.
One improvement is in #186. Could you try this and see if it resolves the issue for you?

npm i https://pkg.pr.new/get-convex/agent/@convex-dev/agent@186

[christiannwamba]

Thanks for the detailed report! The logic in dedupeMessages is supposed to be preferring the completed message. I wonder why it's not... Can you use useUIMessages with {stream: false} and useStreamingUIMessages separately (pointing at the same query) and see what the messages are when it's duplicated? In particular:

• What are the order & stepOrder for the messages that are supposed to match
• What are the statuses of these messages?
• Does useStreamingUIMessages work correctly otherwise in these cases? i.e. does the status & behavior match non-tool-result streaming responses?
• Does useThreadMessages work in this case (on a query with listMessages not listUIMessages)?

Thanks for looking into this! I've run the diagnostics you requested. Here are the findings:

Diagnostic Results

1. useUIMessages with {stream: false}

Result: ✅ No duplicates - Works correctly

• Messages show proper status transitions: success → pending → success
• No stuck streaming deltas
• Trade-off: No visible streaming experience (messages appear instantly when complete)

Logs:

Messages: [
  {"id": "ks7abha9r4wz8g2swchw713mfh7vpvc9", "order": 0, "role": "user", "status": "success", "stepOrder": 0},
  {"id": "ks71ezbwgh42mmb6a5t06bmgfd7vqd1d", "order": 0, "role": "assistant", "status": "success", "stepOrder": 1}
]

2. useStreamingUIMessages separately (with useUIMessages({stream: false}) for DB)

Result: ⚠️ Duplicates appear - Streaming message gets stuck

• DB Messages: Show completed messages with status: "success", stepOrder: 1
• Streaming Messages: Show stuck message with status: "streaming", stepOrder: 3, ID prefixed "stream:"
• Key Issue: Streaming message never transitions from "streaming" to completed after tool approval

Logs:

DB Messages: [
  {"id": "ks75gpq7y7q9fbbrx9av6w636n7vq14q", "order": 1, "role": "assistant", "status": "success", "stepOrder": 1}
]
Streaming Messages: [
  {"id": "stream:m17fmeme6e1tqenz352a8t74m97vq0wt", "order": 1, "role": "assistant", "status": "streaming", "stepOrder": 3}
]

3. useThreadMessages with listMessages

Result: ✅ Works correctly

• All messages show status: "success", streaming: false
• No duplicates
• Note: Similar to Diagnostic 1 - no visible streaming experience

Answers to Your Questions

Q: What are the order & stepOrder for the messages that are supposed to match?

• DB message: order: 1, stepOrder: 1
• Streaming message: order: 1, stepOrder: 3
• They have the same order but different stepOrders, so the deduplication logic doesn't consider them duplicates

Q: What are the statuses of these messages?

• DB message: status: "success"
• Streaming message: status: "streaming" (stuck, never completes)

Q: Does useStreamingUIMessages work correctly otherwise in these cases?

• ❌ No - The streaming message gets stuck at status: "streaming" after tool result approval
• It never transitions to a completed state
• The stepOrder mismatch (3 vs 1) suggests the streaming delta is from a different step in the conversation

Q: Does useThreadMessages work in this case?

• ✅ Yes, useThreadMessages works correctly with listMessages
• Shows all messages with proper status: "success"
• No duplicates or stuck streaming states

[christiannwamba]

@christiannwamba I also would love to know answers to the above questions to help figure out the root cause. One improvement is in #186. Could you try this and see if it resolves the issue for you?

npm i https://pkg.pr.new/get-convex/agent/@convex-dev/agent@186

I tested PR #186 and it fixes
the issue! ✅

After installing the fix with:

npm i https://pkg.pr.new/get-convex/agent/@convex-dev/agent@186

The duplicate messages no longer appear after approving tool calls. Streaming works
correctly and the stuck streaming delta issue is resolved.

Thank you for the quick fix! Will keep testing and let you know if I experience any issues

[christiannwamba]

@ianmacartney I should probably close this. Is the fix in 0.3.1?

[ianmacartney]

There was a release almost including this, but it regressed on performance I believe. So I’m not sure if this made it in. I'll rebase this to update the pkg-pr-new package to include 0.3.1, but will need to follow up later unless someone else can diagnose it

…

On Fri, Nov 28, 2025 at 7:02 AM Christian Nwamba ***@***.***> wrote: *christiannwamba* left a comment (get-convex/agent#185) <#185 (comment)> @ianmacartney <https://github.com/ianmacartney> I should probably close this. Is the fix in 0.3.1? — Reply to this email directly, view it on GitHub <#185 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AACZQW7WA6X3QOIMAFKBS4337BPXXAVCNFSM6AAAAACMEVYXPKVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTKOBZGY2DENBTGI> . You are receiving this because you were mentioned.Message ID: ***@***.***>